samp_sdk/omp/

players.rs

//! Player events straight from the Open Multiplayer server.
//!
//! A plugin that wants `OnPlayerConnect` today goes through Pawn: the SDK
//! detours `amx_Exec` and watches the gamemode's callbacks (see
//! [`crate::omp::events`]). That works on both servers, but it only sees what
//! the script is told, and it costs a detour.
//!
//! Open Multiplayer offers the same events natively: `ICore` hands out an
//! `IPlayerPool`, the pool hands out an `IEventDispatcher<PlayerConnectEventHandler>`,
//! and a component registers a handler on it. No Pawn, no detour — the server
//! calls the plugin directly.
//!
//! ## Slots, per ABI
//!
//! | Method | Itanium | MSVC |
//! | ------ | :-----: | :--: |
//! | `ICore::getPlayers` | 8 | 7 |
//! | `IPlayerPool::getPlayerConnectDispatcher` | 10 | 9 |
//!
//! Itanium values come from the vtable dumps of the official `omp-server`
//! (`PlayerPool` and `Core` keep their symbols). MSVC shifts by one because it
//! emits a single destructor slot where Itanium emits two — the same rule as
//! everywhere else in this module, and `cargo xtask check-abi` re-derives
//! it from the binaries.
//!
//! ## `PlayerConnectEventHandler`
//!
//! Declared in `player.hpp` with no virtual destructor, so four slots on both
//! ABIs:
//!
//! ```text
//! [0] onIncomingConnection(IPlayer&, StringView ip, u16 port)
//! [1] onPlayerConnect(IPlayer&)
//! [2] onPlayerDisconnect(IPlayer&, PeerDisconnectReason)
//! [3] onPlayerClientInit(IPlayer&)
//! ```

use super::component::ICore;
use super::types::{Colour, StringView, UID, Vector3};
use super::vehicles::IVehicle;
use super::vtable::{call_vtable, call_vtable_small_struct, opaque, slots, virtual_fns};

slots! {
    /// Slot of `ICore::getPlayers()`.
    SLOT_GET_PLAYERS: usize = 8, 7;
    /// Slot of `IPlayerPool::getPlayerConnectDispatcher()`.
    SLOT_CONNECT_DISPATCHER: usize = 10, 9;
}

opaque! {
    /// Opaque handle for the server's `IPlayerPool*`.
    pub IPlayerPool;
}

slots! {
    /// Slot of `IPlayer::kick()`.
    SLOT_PLAYER_KICK: usize = 6, 5;
    /// Slot of `IPlayer::isBot()`.
    SLOT_PLAYER_IS_BOT: usize = 8, 7;
    /// Slot of `IPlayer::getName()`.
    SLOT_PLAYER_GET_NAME: usize = 27, 26;
    /// Slot of `IPlayer::setHealth(float)`.
    SLOT_PLAYER_SET_HEALTH: usize = 77, 76;
    /// Slot of `IPlayer::getHealth()`.
    SLOT_PLAYER_GET_HEALTH: usize = 78, 77;
    /// Offset of the `IEntity` subobject inside an `IPlayer`.
    ///
    /// `IPlayer : public IExtensible, public IEntity`, so position, rotation and
    /// virtual world live in a **secondary** vtable rather than the primary one:
    /// the `this` pointer has to be adjusted before indexing. The offset is the
    /// size of `IExtensible`, which is why it matches the one `OmpComponent` uses
    /// for `IUIDProvider`. Derived from clang's record layout for both ABIs.
    pub(crate) ENTITY_OFFSET: isize = 40, 56;
    /// Offset of the `IReadOnlyPool<IPlayer>` subobject inside an `IPlayerPool`.
    ///
    /// Same reasoning as [`ENTITY_OFFSET`]: the pool interface is a secondary base,
    /// so looking a player up by id means adjusting `this` first. From clang's
    /// record layout of `IPlayerPool`.
    PLAYER_POOL_OFFSET: isize = 40, 56;
}

/// `IReadOnlyPool<T>::get(int)` is its first method, and `bounds()` the second.
/// Neither interface declares a destructor, so both ABIs agree.
pub(crate) const SLOT_POOL_GET: usize = 0;
pub(crate) const SLOT_POOL_BOUNDS: usize = 1;

/// `IExtensible::getExtension(UID)` — slot [0] of every entity's primary
/// vtable, since `IExtensible` is the first base and declares it first.
const SLOT_GET_EXTENSION: usize = 0;

/// Slots inside the `IEntity` vtable. It declares no destructor, so the
/// numbering is identical on both ABIs.
pub(crate) const SLOT_ENTITY_GET_ID: usize = 0;
pub(crate) const SLOT_ENTITY_GET_POSITION: usize = 1;
const SLOT_ENTITY_SET_POSITION: usize = 2;
pub(crate) const SLOT_ENTITY_GET_ROTATION: usize = 3;
pub(crate) const SLOT_ENTITY_SET_ROTATION: usize = 4;
const SLOT_ENTITY_GET_VIRTUAL_WORLD: usize = 5;
const SLOT_ENTITY_SET_VIRTUAL_WORLD: usize = 6;

slots! {
    /// Slot of `IPlayer::setMoney(int)`.
    SLOT_PLAYER_SET_MONEY: usize = 62, 61;
    /// Slot of `IPlayer::giveMoney(int)`.
    SLOT_PLAYER_GIVE_MONEY: usize = 63, 62;
    /// Slot of `IPlayer::setArmour(float)`.
    SLOT_PLAYER_SET_ARMOUR: usize = 81, 80;
    /// Slot of `IPlayer::getArmour()`.
    SLOT_PLAYER_GET_ARMOUR: usize = 82, 81;
    /// Slot of `IPlayer::setTeam(int)`.
    SLOT_PLAYER_SET_TEAM: usize = 95, 94;
    /// Slot of `IPlayer::getTeam()`.
    SLOT_PLAYER_GET_TEAM: usize = 96, 95;
    /// Slot of `IPlayer::setSkin(int, bool)`.
    SLOT_PLAYER_SET_SKIN: usize = 97, 96;
    /// Slots of the plain `int` accessors, all reached through
    /// [`player_set_i32`] / [`player_get_i32`]. Every pair is one apart between
    /// ABIs, the usual destructor shift, and comes from `cargo xtask vtable`.
    SLOT_PLAYER_SET_DRUNK: usize = 40, 39;
    SLOT_PLAYER_SET_WANTED: usize = 49, 48;
    SLOT_PLAYER_GET_WANTED: usize = 50, 49;
    SLOT_PLAYER_GET_MONEY: usize = 65, 64;
    SLOT_PLAYER_GET_SKIN: usize = 98, 97;
    SLOT_PLAYER_SET_WEATHER: usize = 107, 106;
    SLOT_PLAYER_SET_INTERIOR: usize = 118, 117;
    SLOT_PLAYER_GET_INTERIOR: usize = 119, 118;
    /// Slot of `IPlayer::setControllable(bool)`.
    SLOT_PLAYER_SET_CONTROLLABLE: usize = 46, 45;
    /// Slot of `IPlayer::setScore(int)`.
    SLOT_PLAYER_SET_SCORE: usize = 79, 78;
    /// Slot of `IPlayer::getScore()`.
    SLOT_PLAYER_GET_SCORE: usize = 80, 79;
    /// Slot of `IPlayer::sendClientMessage(const Colour&, StringView)`.
    SLOT_PLAYER_SEND_MESSAGE: usize = 100, 99;
}

opaque! {
    /// Opaque handle for the server's `IPlayer*`, as received by a handler.
    pub IPlayer;
}

slots! {
    /// Slot of `IPlayerPool::getPlayerSpawnDispatcher()`.
    SLOT_SPAWN_DISPATCHER: usize = 9, 8;
    /// Slot of `IPlayerPool::getPlayerTextDispatcher()`.
    SLOT_TEXT_DISPATCHER: usize = 12, 11;
    /// Slot of `IPlayerPool::getPlayerDamageDispatcher()`.
    SLOT_DAMAGE_DISPATCHER: usize = 15, 14;
    /// Slot of `IPlayerPool::getPlayerStreamDispatcher()`.
    SLOT_STREAM_DISPATCHER: usize = 11, 10;
    /// Slot of `IPlayerPool::getPlayerShotDispatcher()`.
    SLOT_SHOT_DISPATCHER: usize = 13, 12;
    /// Slot of `IPlayerPool::getPlayerChangeDispatcher()`.
    SLOT_CHANGE_DISPATCHER: usize = 14, 13;
    /// Slot of `IPlayerPool::getPlayerClickDispatcher()`.
    SLOT_CLICK_DISPATCHER: usize = 16, 15;
    /// Slot of `IPlayerPool::getPlayerCheckDispatcher()`.
    SLOT_CHECK_DISPATCHER: usize = 17, 16;
    /// Slot of `IPlayerPool::getPlayerUpdateDispatcher()`.
    SLOT_UPDATE_DISPATCHER: usize = 18, 17;
}

opaque! {
    /// Opaque handle for `IEventDispatcher<PlayerConnectEventHandler>*`.
    pub IPlayerConnectDispatcher;
}

/// Why the server dropped a player (`PeerDisconnectReason` in `network.hpp`).
#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DisconnectReason {
    Timeout = 0,
    Quit = 1,
    Kicked = 2,
    Custom = 3,
    ModeEnd = 4,
}

impl DisconnectReason {
    /// Maps the raw value the server passes, treating an unknown one as
    /// [`DisconnectReason::Custom`] rather than transmuting it into a variant
    /// that does not exist.
    #[must_use]
    pub fn from_raw(value: i32) -> Self {
        match value {
            0 => Self::Timeout,
            1 => Self::Quit,
            2 => Self::Kicked,
            4 => Self::ModeEnd,
            _ => Self::Custom,
        }
    }
}

/// `PlayerConnectEventHandler` vtable — Itanium ABI.
#[cfg(not(target_env = "msvc"))]
#[repr(C)]
pub struct PlayerConnectHandlerVTable {
    pub on_incoming_connection:
        unsafe extern "C" fn(*mut PlayerConnectHandler, *mut IPlayer, StringView, u16),
    pub on_player_connect: unsafe extern "C" fn(*mut PlayerConnectHandler, *mut IPlayer),
    pub on_player_disconnect: unsafe extern "C" fn(*mut PlayerConnectHandler, *mut IPlayer, i32),
    pub on_player_client_init: unsafe extern "C" fn(*mut PlayerConnectHandler, *mut IPlayer),
}

/// `PlayerConnectEventHandler` vtable — MSVC ABI (`this` in ECX).
#[cfg(target_env = "msvc")]
#[repr(C)]
pub struct PlayerConnectHandlerVTable {
    pub on_incoming_connection:
        unsafe extern "thiscall" fn(*mut PlayerConnectHandler, *mut IPlayer, StringView, u16),
    pub on_player_connect: unsafe extern "thiscall" fn(*mut PlayerConnectHandler, *mut IPlayer),
    pub on_player_disconnect:
        unsafe extern "thiscall" fn(*mut PlayerConnectHandler, *mut IPlayer, i32),
    pub on_player_client_init: unsafe extern "thiscall" fn(*mut PlayerConnectHandler, *mut IPlayer),
}

/// Object the server calls on player connection events.
///
/// Layout: vtable pointer at offset 0, like every C++ object with virtuals. The
/// server keeps the pointer, so it must outlive the registration — leak it, or
/// keep it alive for the plugin's lifetime and remove it before dropping.
#[repr(C)]
pub struct PlayerConnectHandler {
    vtable: *const PlayerConnectHandlerVTable,
}

// SAFETY: the handler is only ever touched on the server's main thread.
unsafe impl Send for PlayerConnectHandler {}
unsafe impl Sync for PlayerConnectHandler {}

impl PlayerConnectHandler {
    /// Builds a handler backed by `vtable`.
    #[must_use]
    pub fn new(vtable: *const PlayerConnectHandlerVTable) -> Self {
        Self { vtable }
    }
}

opaque! {
    /// Opaque handles for the objects a shot can hit, beyond the vehicle the
    /// [`vehicles`](super::vehicles) module already defines.
    pub IObject;
    /// See [`IObject`].
    pub IPlayerObject;
    /// `PlayerBulletData`, passed by const reference — opaque here, since reading
    /// it means pinning another layout.
    pub PlayerBulletData;
    /// Opaque handle for `IEventDispatcher<PlayerSpawnEventHandler>*`.
    pub IPlayerSpawnDispatcher;
    /// Opaque handle for `IEventDispatcher<PlayerTextEventHandler>*`.
    pub IPlayerTextDispatcher;
    /// Opaque handle for `IEventDispatcher<PlayerDamageEventHandler>*`.
    pub IPlayerDamageDispatcher;
    /// Opaque handle for `IEventDispatcher<PlayerStreamEventHandler>*`.
    pub IPlayerStreamDispatcher;
    /// Opaque handle for `IEventDispatcher<PlayerShotEventHandler>*`.
    pub IPlayerShotDispatcher;
    /// Opaque handle for `IEventDispatcher<PlayerChangeEventHandler>*`.
    pub IPlayerChangeDispatcher;
    /// Opaque handle for `IEventDispatcher<PlayerClickEventHandler>*`.
    pub IPlayerClickDispatcher;
    /// Opaque handle for `IEventDispatcher<PlayerCheckEventHandler>*`.
    pub IPlayerCheckDispatcher;
    /// Opaque handle for `IEventDispatcher<PlayerUpdateEventHandler>*`.
    pub IPlayerUpdateDispatcher;
}

/// Writes a handler vtable struct for both ABIs — the server calls through it,
/// so the convention is the platform's: `extern "C"` on Itanium, `thiscall`
/// on MSVC. None of these handlers declares a virtual destructor, so the slot
/// numbering is the declaration order on both.
macro_rules! handler_vtable {
    (
        $(#[$meta:meta])*
        $name:ident for $handler:ident {
            $($field:ident: fn($($arg:ty),* $(,)?) $(-> $ret:ty)?),* $(,)?
        }
    ) => {
        $(#[$meta])*
        #[cfg(not(target_env = "msvc"))]
        #[repr(C)]
        pub struct $name {
            $(pub $field: unsafe extern "C" fn(*mut $handler, $($arg),*) $(-> $ret)?),*
        }

        $(#[$meta])*
        #[cfg(target_env = "msvc")]
        #[repr(C)]
        pub struct $name {
            $(pub $field: unsafe extern "thiscall" fn(*mut $handler, $($arg),*) $(-> $ret)?),*
        }

        /// Object the server calls through [`
        #[doc = stringify!($name)]
        /// `]. Layout: vtable pointer at offset 0, like any C++ object with
        /// virtuals. The server keeps the pointer, so it must outlive the
        /// registration.
        #[repr(C)]
        pub struct $handler {
            vtable: *const $name,
        }

        // SAFETY: handlers are only ever touched on the server's main thread.
        unsafe impl Send for $handler {}
        unsafe impl Sync for $handler {}

        impl $handler {
            /// Builds a handler backed by `vtable`.
            #[must_use]
            pub fn new(vtable: *const $name) -> Self {
                Self { vtable }
            }
        }
    };
}

handler_vtable! {
    /// `PlayerSpawnEventHandler` — `onPlayerRequestSpawn` returning `false`
    /// denies the spawn.
    PlayerSpawnHandlerVTable for PlayerSpawnHandler {
        on_player_request_spawn: fn(*mut IPlayer) -> bool,
        on_player_spawn: fn(*mut IPlayer),
    }
}

handler_vtable! {
    /// `PlayerTextEventHandler` — `onPlayerText` returning `false` blocks the
    /// message; `onPlayerCommandText` returning `true` marks the command as
    /// handled.
    PlayerTextHandlerVTable for PlayerTextHandler {
        on_player_text: fn(*mut IPlayer, StringView) -> bool,
        on_player_command_text: fn(*mut IPlayer, StringView) -> bool,
    }
}

handler_vtable! {
    /// `PlayerDamageEventHandler`. `killer` is null when nobody killed the
    /// player, and `part` is a `BodyPart` value.
    PlayerDamageHandlerVTable for PlayerDamageHandler {
        on_player_death: fn(*mut IPlayer, *mut IPlayer, i32),
        on_player_take_damage: fn(*mut IPlayer, *mut IPlayer, f32, u32, i32),
        on_player_give_damage: fn(*mut IPlayer, *mut IPlayer, f32, u32, i32),
    }
}

/// `ICore::getPlayers()` — the server's player pool.
///
/// # Safety
/// `core` must be the `ICore*` the server passed to `on_load`.
#[must_use]
pub unsafe fn player_pool(core: *mut ICore) -> *mut IPlayerPool {
    call_vtable!(
        core.cast::<u8>(),
        0,
        SLOT_GET_PLAYERS,
        () -> *mut IPlayerPool,
        (),
        std::ptr::null_mut()
    )
}

/// `IPlayerPool::getPlayerConnectDispatcher()`.
///
/// # Safety
/// `pool` must come from [`player_pool`].
#[must_use]
pub unsafe fn player_connect_dispatcher(pool: *mut IPlayerPool) -> *mut IPlayerConnectDispatcher {
    #[cfg(not(target_env = "msvc"))]
    type GetDispatcherFn = unsafe extern "C" fn(*mut u8) -> *mut IPlayerConnectDispatcher;
    #[cfg(target_env = "msvc")]
    type GetDispatcherFn = unsafe extern "thiscall" fn(*mut u8) -> *mut IPlayerConnectDispatcher;

    let Some((this, f_ptr)) = (unsafe {
        super::vtable::secondary_call_target_ptr(pool.cast::<u8>(), 0, SLOT_CONNECT_DISPATCHER)
    }) else {
        return std::ptr::null_mut();
    };
    let get_dispatcher: GetDispatcherFn = unsafe { std::mem::transmute(f_ptr) };
    unsafe { get_dispatcher(this) }
}

/// Registers `handler` on the dispatcher (`addEventHandler`, slot [0]).
///
/// Returns what the server returned: `false` means the handler was already
/// registered.
///
/// # Safety
/// Both pointers must be valid, and `handler` must outlive the registration.
pub unsafe fn add_player_connect_handler(
    dispatcher: *mut IPlayerConnectDispatcher,
    handler: *mut PlayerConnectHandler,
) -> bool {
    // `IEventDispatcher<T>` declares no destructor, so `addEventHandler` is
    // slot [0] on both ABIs — same layout the Pawn dispatcher uses. The last
    // argument is the priority, `EventPriority_Default`.
    call_vtable!(
        dispatcher.cast::<u8>(),
        0,
        0,
        (*mut PlayerConnectHandler, i8) -> bool,
        (handler, 0),
        false
    )
}

handler_vtable! {
    /// `PlayerStreamEventHandler` — a player entering or leaving another's
    /// stream radius.
    PlayerStreamHandlerVTable for PlayerStreamHandler {
        on_player_stream_in: fn(*mut IPlayer, *mut IPlayer),
        on_player_stream_out: fn(*mut IPlayer, *mut IPlayer),
    }
}

handler_vtable! {
    /// `PlayerShotEventHandler` — returning `false` rejects the shot.
    /// `bullet_data` points at a `PlayerBulletData` the server owns.
    PlayerShotHandlerVTable for PlayerShotHandler {
        on_player_shot_missed: fn(*mut IPlayer, *const PlayerBulletData) -> bool,
        on_player_shot_player: fn(*mut IPlayer, *mut IPlayer, *const PlayerBulletData) -> bool,
        on_player_shot_vehicle: fn(*mut IPlayer, *mut IVehicle, *const PlayerBulletData) -> bool,
        on_player_shot_object: fn(*mut IPlayer, *mut IObject, *const PlayerBulletData) -> bool,
        on_player_shot_player_object:
            fn(*mut IPlayer, *mut IPlayerObject, *const PlayerBulletData) -> bool,
    }
}

handler_vtable! {
    /// `PlayerChangeEventHandler`. `PlayerState` and the key masks arrive as
    /// plain integers.
    PlayerChangeHandlerVTable for PlayerChangeHandler {
        on_player_score_change: fn(*mut IPlayer, i32),
        on_player_name_change: fn(*mut IPlayer, StringView),
        on_player_interior_change: fn(*mut IPlayer, u32, u32),
        on_player_state_change: fn(*mut IPlayer, i32, i32),
        on_player_key_state_change: fn(*mut IPlayer, u32, u32),
    }
}

handler_vtable! {
    /// `PlayerClickEventHandler`. `Vector3` is passed by value, as the header
    /// declares it.
    PlayerClickHandlerVTable for PlayerClickHandler {
        on_player_click_map: fn(*mut IPlayer, Vector3),
        on_player_click_player: fn(*mut IPlayer, *mut IPlayer, i32),
    }
}

handler_vtable! {
    /// `PlayerCheckEventHandler` — the reply to a client check request.
    PlayerCheckHandlerVTable for PlayerCheckHandler {
        on_client_check_response: fn(*mut IPlayer, i32, i32, i32),
    }
}

handler_vtable! {
    /// `PlayerUpdateEventHandler` — fires for every player on every server
    /// tick, so keep the body short. Returning `false` drops the update.
    ///
    /// `now` is a `TimePoint` (`steady_clock`, nanoseconds): one 64-bit value
    /// passed by value, which on i686 lands on the stack either way.
    PlayerUpdateHandlerVTable for PlayerUpdateHandler {
        on_player_update: fn(*mut IPlayer, i64) -> bool,
    }
}

virtual_fns! {
    /// Calls `IPlayer::kick()` — drops the player from the server.
    ///
    /// # Safety
    /// `player` must be an `IPlayer*` the server handed to a handler, and still
    /// connected.
    pub fn player_kick(player: IPlayer) = [0, SLOT_PLAYER_KICK];

    /// `IPlayer::isBot()` — whether this "player" is an NPC.
    ///
    /// # Safety
    /// See [`player_kick`].
    #[must_use]
    pub fn player_is_bot(player: IPlayer) -> bool = [0, SLOT_PLAYER_IS_BOT] or false;
}

/// `IPlayer::getName()` — the player's name, copied into a `String`.
///
/// The server returns a `StringView` into memory it owns, so the bytes are
/// copied out rather than borrowed. `None` when the view is empty or not valid
/// UTF-8.
///
/// # Safety
/// See [`player_kick`].
#[must_use]
pub unsafe fn player_name(player: *mut IPlayer) -> Option<String> {
    let view = call_vtable_small_struct!(
        player.cast::<u8>(),
        0,
        SLOT_PLAYER_GET_NAME,
        StringView,
        StringView::EMPTY
    )?;
    unsafe { view.to_owned_string() }
}

virtual_fns! {
    /// `IPlayer::getHealth()`.
    ///
    /// # Safety
    /// See [`player_kick`].
    #[must_use]
    pub fn player_health(player: IPlayer) -> f32 = [0, SLOT_PLAYER_GET_HEALTH] or 0.0;

    /// `IPlayer::setHealth(float)`.
    ///
    /// # Safety
    /// See [`player_kick`].
    pub fn player_set_health(player: IPlayer, health: f32) = [0, SLOT_PLAYER_SET_HEALTH];

    /// `IPlayer::getScore()`.
    ///
    /// # Safety
    /// See [`player_kick`].
    #[must_use]
    pub fn player_score(player: IPlayer) -> i32 = [0, SLOT_PLAYER_GET_SCORE] or 0;

    /// `IPlayer::setScore(int)`.
    ///
    /// Unlike health, the score is the server's own value — a client cannot
    /// overwrite it on the next sync packet.
    ///
    /// # Safety
    /// See [`player_kick`].
    pub fn player_set_score(player: IPlayer, score: i32) = [0, SLOT_PLAYER_SET_SCORE];

    /// `IEntity::getPosition()` — where the player is.
    ///
    /// A `Vector3` is twelve bytes, too large to come back in registers, so the
    /// caller supplies a hidden pointer. The details differ per ABI and are easy to
    /// get wrong by hand — on i386 System V the pointer goes **before** `this` and
    /// the callee pops it (`ret $0x4` in the server's own `Player::getPosition`),
    /// so writing the pointer as an ordinary argument unbalances the stack.
    ///
    /// Declaring the return type and letting the compiler apply the rule avoids all
    /// of that.
    ///
    /// # Safety
    /// See [`player_kick`].
    #[must_use]
    pub fn player_position(player: IPlayer) -> Vector3 = [ENTITY_OFFSET, SLOT_ENTITY_GET_POSITION] or Vector3::ZERO;

    /// `IEntity::setPosition(Vector3)` — teleports the player.
    ///
    /// # Safety
    /// See [`player_kick`].
    pub fn player_set_position(player: IPlayer, position: Vector3) = [ENTITY_OFFSET, SLOT_ENTITY_SET_POSITION];

    /// `IEntity::getVirtualWorld()`.
    ///
    /// # Safety
    /// See [`player_kick`].
    #[must_use]
    pub fn player_virtual_world(player: IPlayer) -> i32 = [ENTITY_OFFSET, SLOT_ENTITY_GET_VIRTUAL_WORLD] or 0;

    /// `IEntity::setVirtualWorld(int)`.
    ///
    /// # Safety
    /// See [`player_kick`].
    pub fn player_set_virtual_world(player: IPlayer, world: i32) = [ENTITY_OFFSET, SLOT_ENTITY_SET_VIRTUAL_WORLD];

    /// `IPlayer::setMoney(int)`.
    ///
    /// # Safety
    /// See [`player_kick`].
    pub fn player_set_money(player: IPlayer, amount: i32) = [0, SLOT_PLAYER_SET_MONEY];

    /// `IPlayer::giveMoney(int)` — adds to what the player already has.
    ///
    /// # Safety
    /// See [`player_kick`].
    pub fn player_give_money(player: IPlayer, amount: i32) = [0, SLOT_PLAYER_GIVE_MONEY];

    /// `IPlayer::setTeam(int)`.
    ///
    /// # Safety
    /// See [`player_kick`].
    pub fn player_set_team(player: IPlayer, team: i32) = [0, SLOT_PLAYER_SET_TEAM];

    /// `IPlayer::getTeam()`.
    ///
    /// # Safety
    /// See [`player_kick`].
    #[must_use]
    pub fn player_team(player: IPlayer) -> i32 = [0, SLOT_PLAYER_GET_TEAM] or 0;

    /// `IPlayer::setArmour(float)`.
    ///
    /// # Safety
    /// See [`player_kick`].
    pub fn player_set_armour(player: IPlayer, armour: f32) = [0, SLOT_PLAYER_SET_ARMOUR];

    /// `IPlayer::getArmour()`.
    ///
    /// # Safety
    /// See [`player_kick`].
    #[must_use]
    pub fn player_armour(player: IPlayer) -> f32 = [0, SLOT_PLAYER_GET_ARMOUR] or 0.0;

    /// `IPlayer::setSkin(int, bool)` — `send` asks the server to tell the other
    /// players about the change, which is what a script normally wants.
    ///
    /// # Safety
    /// See [`player_kick`].
    pub fn player_set_skin(player: IPlayer, skin: i32, send: bool) = [0, SLOT_PLAYER_SET_SKIN];

    /// `IEntity::getID()` — the id Pawn scripts know this player by.
    ///
    /// # Safety
    /// See [`player_kick`].
    #[must_use]
    pub fn player_id(player: IPlayer) -> i32 = [ENTITY_OFFSET, SLOT_ENTITY_GET_ID] or -1;

    /// `IReadOnlyPool<IPlayer>::get(int)` — the player with that id, or null.
    ///
    /// Answers "who is player 7?" without touching the pool's hash set, whose
    /// layout belongs to `robin_hood` and would have to be mirrored to iterate.
    ///
    /// # Safety
    /// `pool` must come from [`player_pool`].
    #[must_use]
    pub fn player_by_id(pool: IPlayerPool, id: i32) -> *mut IPlayer = [PLAYER_POOL_OFFSET, SLOT_POOL_GET] or std::ptr::null_mut();

    /// `IPlayer::getMoney()`.
    ///
    /// # Safety
    /// See [`player_kick`].
    #[must_use]
    pub fn player_money(player: IPlayer) -> i32 = [0, SLOT_PLAYER_GET_MONEY] or 0;

    /// `IPlayer::getSkin()`.
    ///
    /// # Safety
    /// See [`player_kick`].
    #[must_use]
    pub fn player_skin(player: IPlayer) -> i32 = [0, SLOT_PLAYER_GET_SKIN] or 0;

    /// `IPlayer::setWantedLevel(unsigned)` — zero to six, as the game shows.
    ///
    /// # Safety
    /// See [`player_kick`].
    pub fn player_set_wanted_level(player: IPlayer, level: u32) = [0, SLOT_PLAYER_SET_WANTED];

    /// `IPlayer::getWantedLevel()`.
    ///
    /// # Safety
    /// See [`player_kick`].
    #[must_use]
    pub fn player_wanted_level(player: IPlayer) -> u32 = [0, SLOT_PLAYER_GET_WANTED] or 0;

    /// `IPlayer::setInterior(unsigned)`.
    ///
    /// # Safety
    /// See [`player_kick`].
    pub fn player_set_interior(player: IPlayer, interior: u32) = [0, SLOT_PLAYER_SET_INTERIOR];

    /// `IPlayer::getInterior()`.
    ///
    /// # Safety
    /// See [`player_kick`].
    #[must_use]
    pub fn player_interior(player: IPlayer) -> u32 = [0, SLOT_PLAYER_GET_INTERIOR] or 0;

    /// `IPlayer::setWeather(int)` — for this player alone.
    ///
    /// # Safety
    /// See [`player_kick`].
    pub fn player_set_weather(player: IPlayer, weather: i32) = [0, SLOT_PLAYER_SET_WEATHER];

    /// `IPlayer::setDrunkLevel(int)`.
    ///
    /// # Safety
    /// See [`player_kick`].
    pub fn player_set_drunk_level(player: IPlayer, level: i32) = [0, SLOT_PLAYER_SET_DRUNK];

    /// `IPlayer::setControllable(bool)` — `false` freezes the player.
    ///
    /// # Safety
    /// See [`player_kick`].
    pub fn player_set_controllable(player: IPlayer, controllable: bool) = [0, SLOT_PLAYER_SET_CONTROLLABLE];
}

/// The range of ids a pool can hand out, as `IReadOnlyPool<T>::bounds()`
/// reports it: inclusive on both ends.
#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct PoolBounds {
    pub first: usize,
    pub last: usize,
}

/// `IReadOnlyPool<T>::bounds()` for any pool, given the offset of its
/// subobject.
///
/// Walking these ids and asking for each one is how this SDK iterates a pool.
/// The alternative, `entries()`, returns a `robin_hood` hash set whose layout
/// would have to be mirrored, and mirroring it wrong reads the server's memory
/// at random.
///
/// # Safety
/// `pool` must point at an object carrying `IReadOnlyPool<T>` at `offset`.
#[must_use]
pub unsafe fn pool_bounds(pool: *mut u8, offset: isize) -> PoolBounds {
    // `bounds()` returns a `Pair<size_t, size_t>`. Eight bytes, but the two
    // ABIs disagree on how: GCC hands it back in registers, while MSVC sees a
    // type with a constructor and returns it through a hidden pointer. Rust
    // cannot infer that difference from a `#[repr(C)]` struct — it applies the
    // C rule, registers on both — so the MSVC side is spelled out.
    #[cfg(not(target_env = "msvc"))]
    type BoundsFn = unsafe extern "C" fn(*mut u8) -> PoolBounds;
    #[cfg(target_env = "msvc")]
    type BoundsFn = unsafe extern "thiscall" fn(*mut u8, *mut PoolBounds) -> *mut PoolBounds;

    // An empty range: `first > last`, so a loop over it runs zero times.
    let empty = PoolBounds { first: 1, last: 0 };
    let Some((this, f_ptr)) =
        (unsafe { super::vtable::secondary_call_target_ptr(pool, offset, SLOT_POOL_BOUNDS) })
    else {
        return empty;
    };
    let bounds: BoundsFn = unsafe { std::mem::transmute(f_ptr) };

    #[cfg(not(target_env = "msvc"))]
    let result = unsafe { bounds(this) };

    #[cfg(target_env = "msvc")]
    let result = {
        let mut out = empty;
        unsafe { bounds(this, &raw mut out) };
        out
    };

    result
}

/// Every player currently in the pool.
///
/// Named `all_players` rather than `players`, which at a call site would read
/// as the module of that name.
///
/// Named  rather than  so it does not read as the module
/// of the same name at a call site.
///
/// Walks the ids `bounds()` reports and keeps the ones the pool answers for, so
/// a gap in the middle costs one call and nothing else.
///
/// # Safety
/// `pool` must come from [`player_pool`].
#[must_use]
pub unsafe fn all_players(pool: *mut IPlayerPool) -> Vec<*mut IPlayer> {
    let bounds = unsafe { pool_bounds(pool.cast::<u8>(), PLAYER_POOL_OFFSET) };
    let mut found = Vec::new();
    for id in bounds.first..=bounds.last {
        let Ok(id) = i32::try_from(id) else { break };
        let player = unsafe { player_by_id(pool, id) };
        if !player.is_null() {
            found.push(player);
        }
    }
    found
}

/// The player's extension registered under `uid`, or null — what the C++
/// side's `queryExtension<T>()` answers.
///
/// Components attach their per-player data with `addExtension`, which files it
/// in the extension map; the virtual `getExtension` only covers extensions a
/// class provides by overriding it, and returns null otherwise. `queryExtension`
/// looks in the map first and falls back to the virtual, and so does this: the
/// map through [`extension`](super::extensions::extension), then
/// `IExtensible::getExtension(UID)`.
///
/// The generated accessors (`player_dialogs`, `player_objects`, ...) return the
/// same thing already typed.
///
/// # Safety
/// See [`player_kick`].
#[must_use]
pub unsafe fn player_extension(player: *mut IPlayer, uid: UID) -> *mut u8 {
    let attached = unsafe { super::extensions::extension(player.cast::<u8>(), uid) };
    if !attached.is_null() {
        return attached;
    }
    call_vtable!(
        player.cast::<u8>(),
        0,
        SLOT_GET_EXTENSION,
        (UID) -> *mut u8,
        (uid),
        std::ptr::null_mut()
    )
}

/// `IPlayer::sendClientMessage(const Colour&, StringView)` — a chat line for
/// this player only.
///
/// `colour` is RGBA, the order [`Colour`] stores. The text is borrowed for the
/// duration of the call: the server copies what it needs, and a `StringView`
/// carries a length, so no NUL terminator is required.
///
/// # Safety
/// See [`player_kick`].
pub unsafe fn player_send_message(player: *mut IPlayer, colour: Colour, text: &str) {
    let text = StringView::of(text);
    call_vtable!(
        player.cast::<u8>(),
        0,
        SLOT_PLAYER_SEND_MESSAGE,
        (*const Colour, StringView) -> (),
        (&raw const colour, text),
        ()
    )
}

/// Writes the `get<X>Dispatcher` + `add_<x>_handler` pair for one event group.
macro_rules! dispatcher_pair {
    ($getter:ident -> $dispatcher:ident @ $slot:ident, $adder:ident($handler:ident)) => {
        /// The pool's dispatcher for this event group.
        ///
        /// # Safety
        /// `pool` must come from [`player_pool`].
        #[must_use]
        pub unsafe fn $getter(pool: *mut IPlayerPool) -> *mut $dispatcher {
            #[cfg(not(target_env = "msvc"))]
            type GetFn = unsafe extern "C" fn(*mut u8) -> *mut $dispatcher;
            #[cfg(target_env = "msvc")]
            type GetFn = unsafe extern "thiscall" fn(*mut u8) -> *mut $dispatcher;

            let Some((this, f_ptr)) =
                (unsafe { super::vtable::secondary_call_target_ptr(pool.cast::<u8>(), 0, $slot) })
            else {
                return std::ptr::null_mut();
            };
            let get: GetFn = unsafe { std::mem::transmute(f_ptr) };
            unsafe { get(this) }
        }

        /// Registers `handler` on the dispatcher (`addEventHandler`, slot [0]).
        ///
        /// Returns what the server returned: `false` means it was already
        /// registered.
        ///
        /// # Safety
        /// Both pointers must be valid, and `handler` must outlive the
        /// registration.
        pub unsafe fn $adder(dispatcher: *mut $dispatcher, handler: *mut $handler) -> bool {
            call_vtable!(
                dispatcher.cast::<u8>(),
                0,
                0,
                (*mut $handler, i8) -> bool,
                (handler, 0),
                false
            )
        }
    };
}

dispatcher_pair!(player_spawn_dispatcher -> IPlayerSpawnDispatcher @ SLOT_SPAWN_DISPATCHER,
                 add_player_spawn_handler(PlayerSpawnHandler));
dispatcher_pair!(player_text_dispatcher -> IPlayerTextDispatcher @ SLOT_TEXT_DISPATCHER,
                 add_player_text_handler(PlayerTextHandler));
dispatcher_pair!(player_damage_dispatcher -> IPlayerDamageDispatcher @ SLOT_DAMAGE_DISPATCHER,
                 add_player_damage_handler(PlayerDamageHandler));

dispatcher_pair!(player_stream_dispatcher -> IPlayerStreamDispatcher @ SLOT_STREAM_DISPATCHER,
                 add_player_stream_handler(PlayerStreamHandler));
dispatcher_pair!(player_shot_dispatcher -> IPlayerShotDispatcher @ SLOT_SHOT_DISPATCHER,
                 add_player_shot_handler(PlayerShotHandler));
dispatcher_pair!(player_change_dispatcher -> IPlayerChangeDispatcher @ SLOT_CHANGE_DISPATCHER,
                 add_player_change_handler(PlayerChangeHandler));
dispatcher_pair!(player_click_dispatcher -> IPlayerClickDispatcher @ SLOT_CLICK_DISPATCHER,
                 add_player_click_handler(PlayerClickHandler));
dispatcher_pair!(player_check_dispatcher -> IPlayerCheckDispatcher @ SLOT_CHECK_DISPATCHER,
                 add_player_check_handler(PlayerCheckHandler));
dispatcher_pair!(player_update_dispatcher -> IPlayerUpdateDispatcher @ SLOT_UPDATE_DISPATCHER,
                 add_player_update_handler(PlayerUpdateHandler));

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn slots_match_the_official_binaries() {
        // Dumped from `omp-server`: Core [8] getPlayers, PlayerPool [10]
        // getPlayerConnectDispatcher. MSVC drops one destructor slot.
        #[cfg(not(target_env = "msvc"))]
        {
            assert_eq!(SLOT_GET_PLAYERS, 8);
            assert_eq!(SLOT_CONNECT_DISPATCHER, 10);
        }
        #[cfg(target_env = "msvc")]
        {
            assert_eq!(SLOT_GET_PLAYERS, 7);
            assert_eq!(SLOT_CONNECT_DISPATCHER, 9);
        }
    }

    #[test]
    fn the_other_dispatcher_slots_match_the_dump() {
        // From the `PlayerPool` vtable of the official `omp-server`:
        // [9] spawn, [10] connect, [12] text, [15] damage.
        #[cfg(not(target_env = "msvc"))]
        {
            assert_eq!(SLOT_SPAWN_DISPATCHER, 9);
            assert_eq!(SLOT_TEXT_DISPATCHER, 12);
            assert_eq!(SLOT_DAMAGE_DISPATCHER, 15);
        }
        #[cfg(target_env = "msvc")]
        {
            assert_eq!(SLOT_SPAWN_DISPATCHER, 8);
            assert_eq!(SLOT_TEXT_DISPATCHER, 11);
            assert_eq!(SLOT_DAMAGE_DISPATCHER, 14);
        }
    }

    #[test]
    fn every_handler_vtable_has_the_slots_its_header_declares() {
        let pointer = std::mem::size_of::<*const ()>();
        assert_eq!(std::mem::size_of::<PlayerSpawnHandlerVTable>(), 2 * pointer);
        assert_eq!(std::mem::size_of::<PlayerTextHandlerVTable>(), 2 * pointer);
        assert_eq!(
            std::mem::size_of::<PlayerDamageHandlerVTable>(),
            3 * pointer
        );
        assert_eq!(std::mem::offset_of!(PlayerSpawnHandler, vtable), 0);
        assert_eq!(std::mem::offset_of!(PlayerTextHandler, vtable), 0);
        assert_eq!(std::mem::offset_of!(PlayerDamageHandler, vtable), 0);
    }

    #[test]
    fn the_remaining_dispatcher_slots_match_the_dump() {
        // PlayerPool vtable of the official `omp-server`: [11] stream,
        // [13] shot, [14] change, [16] click, [17] check, [18] update.
        #[cfg(not(target_env = "msvc"))]
        let expected = [11, 13, 14, 16, 17, 18];
        #[cfg(target_env = "msvc")]
        let expected = [10, 12, 13, 15, 16, 17];
        assert_eq!(
            [
                SLOT_STREAM_DISPATCHER,
                SLOT_SHOT_DISPATCHER,
                SLOT_CHANGE_DISPATCHER,
                SLOT_CLICK_DISPATCHER,
                SLOT_CHECK_DISPATCHER,
                SLOT_UPDATE_DISPATCHER,
            ],
            expected
        );
    }

    #[test]
    fn the_remaining_vtables_have_the_slots_their_headers_declare() {
        let p = std::mem::size_of::<*const ()>();
        assert_eq!(std::mem::size_of::<PlayerStreamHandlerVTable>(), 2 * p);
        assert_eq!(std::mem::size_of::<PlayerShotHandlerVTable>(), 5 * p);
        assert_eq!(std::mem::size_of::<PlayerChangeHandlerVTable>(), 5 * p);
        assert_eq!(std::mem::size_of::<PlayerClickHandlerVTable>(), 2 * p);
        assert_eq!(std::mem::size_of::<PlayerCheckHandlerVTable>(), p);
        assert_eq!(std::mem::size_of::<PlayerUpdateHandlerVTable>(), p);
    }

    #[test]
    fn player_method_slots_match_the_dump() {
        // `Player` vtable of the official `omp-server`: [6] kick, [8] isBot,
        // [27] getName. MSVC drops the second destructor slot, and no
        // `IEntity` override (secondary base) sits before any of these, so the
        // shift is exactly one. Unlike the component classes, the Windows
        // server carries no RTTI for `Player`, so these cannot be re-derived
        // from the binary — `cargo xtask vtable` derives them from the
        // headers with clang, and a running server proves them.
        #[cfg(not(target_env = "msvc"))]
        let expected = [6, 8, 27, 77, 78, 79, 80, 100];
        #[cfg(target_env = "msvc")]
        let expected = [5, 7, 26, 76, 77, 78, 79, 99];

        // The plain accessors added later, same source, same shift.
        #[cfg(not(target_env = "msvc"))]
        assert_eq!(
            [
                SLOT_PLAYER_SET_DRUNK,
                SLOT_PLAYER_SET_CONTROLLABLE,
                SLOT_PLAYER_SET_WANTED,
                SLOT_PLAYER_GET_WANTED,
                SLOT_PLAYER_GET_MONEY,
                SLOT_PLAYER_GET_SKIN,
                SLOT_PLAYER_SET_WEATHER,
                SLOT_PLAYER_SET_INTERIOR,
                SLOT_PLAYER_GET_INTERIOR,
            ],
            [40, 46, 49, 50, 65, 98, 107, 118, 119]
        );
        #[cfg(target_env = "msvc")]
        assert_eq!(
            [
                SLOT_PLAYER_SET_DRUNK,
                SLOT_PLAYER_SET_CONTROLLABLE,
                SLOT_PLAYER_SET_WANTED,
                SLOT_PLAYER_GET_WANTED,
                SLOT_PLAYER_GET_MONEY,
                SLOT_PLAYER_GET_SKIN,
                SLOT_PLAYER_SET_WEATHER,
                SLOT_PLAYER_SET_INTERIOR,
                SLOT_PLAYER_GET_INTERIOR,
            ],
            [39, 45, 48, 49, 64, 97, 106, 117, 118]
        );
        assert_eq!(
            [
                SLOT_PLAYER_KICK,
                SLOT_PLAYER_IS_BOT,
                SLOT_PLAYER_GET_NAME,
                SLOT_PLAYER_SET_HEALTH,
                SLOT_PLAYER_GET_HEALTH,
                SLOT_PLAYER_SET_SCORE,
                SLOT_PLAYER_GET_SCORE,
                SLOT_PLAYER_SEND_MESSAGE,
            ],
            expected
        );
    }

    #[test]
    fn the_entity_subobject_sits_where_iextensible_ends() {
        // clang's record layout for `IPlayer`: the `IEntity` base starts at 40
        // under Itanium and 56 under MSVC — the size of `IExtensible` on each,
        // the same number `OmpComponent` uses for its `IUIDProvider`.
        #[cfg(not(target_env = "msvc"))]
        assert_eq!(ENTITY_OFFSET, 40);
        #[cfg(target_env = "msvc")]
        assert_eq!(ENTITY_OFFSET, 56);

        // `IEntity` declares no destructor, so both ABIs number it the same.
        assert_eq!(
            [
                SLOT_ENTITY_GET_POSITION,
                SLOT_ENTITY_SET_POSITION,
                SLOT_ENTITY_GET_VIRTUAL_WORLD,
                SLOT_ENTITY_SET_VIRTUAL_WORLD,
            ],
            [1, 2, 5, 6]
        );
    }

    #[test]
    fn handler_layout_is_a_bare_vtable_pointer() {
        assert_eq!(std::mem::offset_of!(PlayerConnectHandler, vtable), 0);
        assert_eq!(
            std::mem::size_of::<PlayerConnectHandler>(),
            std::mem::size_of::<*const ()>()
        );
        assert_eq!(
            std::mem::size_of::<PlayerConnectHandlerVTable>(),
            4 * std::mem::size_of::<*const ()>(),
            "four slots: no virtual destructor in the header"
        );
    }

    #[test]
    fn unknown_disconnect_reason_does_not_invent_a_variant() {
        assert_eq!(DisconnectReason::from_raw(1), DisconnectReason::Quit);
        assert_eq!(DisconnectReason::from_raw(99), DisconnectReason::Custom);
    }
}