"""Type stubs for bridge — auto-completion & static analysis."""
from __future__ import annotations
from typing import Any, Awaitable, Callable, Dict, Iterator, List, Optional

from bridge.connection import BridgeConnection
from bridge.wrappers import ProxyBase as ProxyBase
from bridge.types import (
    EnumValue as EnumValue,
    RaycastResult as RaycastResult,
    BridgeCall as BridgeCall,
    async_task as async_task,
    BridgeMethod as BridgeMethod,
)

# ── Errors ────────────────────────────────────────────────────────────

class BridgeError(Exception): ...
class EntityGoneException(BridgeError): ...
class ConnectionError(BridgeError): ...  # noqa: A001
class TimeoutError(BridgeError): ...  # noqa: A001
class AtomicAbortError(BridgeError): ...
class PlayerOfflineException(BridgeError): ...
class WorldNotLoadedException(BridgeError): ...
class ChunkNotLoadedException(BridgeError): ...
class InvalidLocationError(BridgeError): ...
class InvalidMaterialError(BridgeError): ...
class InvalidItemError(BridgeError): ...
class MethodNotFoundError(BridgeError): ...
class ClassNotFoundError(BridgeError): ...
class AccessDeniedError(BridgeError): ...
class InvalidEventError(BridgeError): ...
class CommandRegistrationError(BridgeError): ...
class ConfigError(BridgeError): ...
class UnsupportedFormatError(BridgeError): ...
class InvalidEnumError(BridgeError): ...
class SlotOutOfRangeError(BridgeError): ...
class PermissionError(BridgeError): ...  # noqa: A001

# ── Enum types ────────────────────────────────────────────────────────

class Material(EnumValue):
    def __init__(self, name: str, _name: str | None = None) -> None: ...

class Biome(EnumValue): ...
class EffectType(EnumValue): ...
class AttributeType(EnumValue): ...
class GameMode(EnumValue): ...
class Sound(EnumValue): ...
class Particle(EnumValue): ...
class Difficulty(EnumValue): ...
class DamageCause(EnumValue): ...
class ItemFlag(EnumValue): ...
class EquipmentSlot(EnumValue): ...
class DyeColor(EnumValue): ...
class SpawnReason(EnumValue): ...
class EntityCategory(EnumValue): ...
class EntityPose(EnumValue): ...
class BlockFace(EnumValue): ...
class TreeType(EnumValue): ...
class WeatherType(EnumValue): ...
class WorldType(EnumValue): ...
class Action(EnumValue): ...
class ChatColor(EnumValue): ...
class EventPriority(EnumValue): ...
class TeleportCause(EnumValue): ...
class InventoryType(EnumValue): ...
class Billboard(EnumValue): ...
class BarFlag(EnumValue): ...

class BarColor(EnumValue): ...
class BarStyle(EnumValue): ...
class EntityType(EnumValue): ...

class Enchantment(EnumValue):
    @classmethod
    def all(cls) -> BridgeCall: ...
    @classmethod
    def for_item(cls, item: Material | EnumValue | str) -> BridgeCall: ...

# ── Event ─────────────────────────────────────────────────────────────

class Event:
    fields: dict[str, Any]
    def cancel(self) -> Awaitable[None]: ...
    player: Player
    entity: Entity
    damager: Entity | Block | None
    block: Block
    world: World
    location: Location
    item: Item
    inventory: Inventory
    chunk: Chunk
    damage: float
    final_damage: float
    damage_cause: Any
    to: Location | Any
    source: Any
    cause: Any
    reason: Any
    action: Any
    hand: Any
    click: Any
    slot: int
    new_slot: int
    previous_slot: int
    velocity: Vector
    message: str
    recipients: Any
    is_flying: bool
    is_sneaking: bool
    is_sprinting: bool
    target: Entity | None
    drops: list[Any]
    death_message: str
    join_message: str
    quit_message: str
    amount: float | int
    old_level: int
    new_level: int
    owner: Player | None
    mount: Entity
    dismounted: Entity
    combuster: Entity
    duration: float
    force: float
    bow: Item
    projectile: Entity
    hit_entity: Entity | None
    hit_block: Block | None
    blocks: list[Block]
    new_state: Any
    to_block: Block
    direction: Any
    old_current: int
    new_current: int
    material: Any
    insta_break: bool
    vehicle: Entity
    attacker: Entity | None
    advancement: Any
    animation: Any
    new_game_mode: Any
    repair_amount: int
    statistic: Any
    locale: str
    hostname: str
    address: Any
    remover: Entity | None
    lightning: Entity
    previous_location: Location
    species: Any
    fuel: Any
    power: int
    result: Any
    recipe: Any
    enchants: Any
    offers: Any
    lines: list[str]
    sender: Any
    command: str

# ── WorldTime ─────────────────────────────────────────────────────────

class WorldTime:
    DAWN: WorldTime
    NOON: WorldTime
    DUSK: WorldTime
    MIDNIGHT: WorldTime
    ticks: int
    def __init__(self, ticks: int) -> None: ...
    @classmethod
    def from_hours(cls, hours: float) -> WorldTime: ...
    @property
    def hours(self) -> float: ...
    @property
    def is_day(self) -> bool: ...
    @property
    def is_night(self) -> bool: ...
    def __eq__(self, other: object) -> bool: ...
    def __hash__(self) -> int: ...
    def __int__(self) -> int: ...
    def __repr__(self) -> str: ...

# ── Entity ────────────────────────────────────────────────────────────

class Entity(ProxyBase):
    @classmethod
    def spawn(cls, entity_type: EntityType | str, location: Location, **kwargs: Any) -> Awaitable[Entity]: ...
    def __bool__(self) -> bool: ...
    def __eq__(self, other: object) -> bool: ...
    def __hash__(self) -> int: ...
    uuid: str
    type: EntityType
    location: Location
    world: World
    equipment: Any
    inventory: Inventory
    held_item: Item
    is_projectile: bool
    shooter: Entity | Player | Block | None
    is_tamed: bool
    owner: Player | None
    owner_uuid: str | None
    owner_name: str | None
    source: Entity | Player | None
    yaw: float
    pitch: float
    look_direction: Vector
    is_dead: bool
    is_alive: bool
    is_valid: bool
    height: float
    width: float
    bounding_box: dict
    max_fire_ticks: int
    metadata: dict[str, Any]

    @property
    def velocity(self) -> Vector: ...
    @velocity.setter
    def velocity(self, vector: Vector) -> None: ...
    @property
    def fire_ticks(self) -> int: ...
    @fire_ticks.setter
    def fire_ticks(self, ticks: int) -> None: ...
    @property
    def custom_name(self) -> Any: ...
    @custom_name.setter
    def custom_name(self, name: str) -> None: ...
    @custom_name.deleter
    def custom_name(self) -> None: ...
    @property
    def custom_name_visible(self) -> bool: ...
    @custom_name_visible.setter
    def custom_name_visible(self, value: bool) -> None: ...
    @property
    def target(self) -> Entity | None: ...
    @target.setter
    def target(self, entity: Entity | None) -> None: ...
    @target.deleter
    def target(self) -> None: ...
    @property
    def is_aware(self) -> bool: ...
    @is_aware.setter
    def is_aware(self, aware: bool) -> None: ...
    @property
    def gravity(self) -> bool: ...
    @gravity.setter
    def gravity(self, value: bool) -> None: ...
    @property
    def glowing(self) -> bool: ...
    @glowing.setter
    def glowing(self, value: bool) -> None: ...
    @property
    def invisible(self) -> bool: ...
    @invisible.setter
    def invisible(self, value: bool) -> None: ...
    @property
    def invulnerable(self) -> bool: ...
    @invulnerable.setter
    def invulnerable(self, value: bool) -> None: ...
    @property
    def silent(self) -> bool: ...
    @silent.setter
    def silent(self, value: bool) -> None: ...
    @property
    def persistent(self) -> bool: ...
    @persistent.setter
    def persistent(self, value: bool) -> None: ...
    @property
    def collidable(self) -> bool: ...
    @collidable.setter
    def collidable(self, value: bool) -> None: ...
    @property
    def portal_cooldown(self) -> int: ...
    @portal_cooldown.setter
    def portal_cooldown(self, ticks: int) -> None: ...
    @property
    def freeze_ticks(self) -> int: ...
    @freeze_ticks.setter
    def freeze_ticks(self, ticks: int) -> None: ...

    def teleport(self, location: Location) -> Awaitable[None]: ...
    def remove(self) -> Awaitable[None]: ...
    def damage(self, amount: float) -> Awaitable[None]: ...
    def add_passenger(self, entity: Entity) -> Awaitable[bool]: ...
    def remove_passenger(self, entity: Entity) -> Awaitable[bool]: ...
    passengers: list[Entity]
    def pathfind_to(self, location: Location, speed: float = 1.0) -> bool: ...
    def stop_pathfinding(self) -> Awaitable[None]: ...
    def has_line_of_sight(self, entity: Entity) -> bool: ...
    def look_at(self, location: Location) -> Awaitable[None]: ...

    goal_types: list[str]
    def remove_goal(self, goal_key: str) -> bool: ...
    def remove_all_goals(self) -> Awaitable[None]: ...

    def add_tag(self, tag: str) -> None: ...
    def remove_tag(self, tag: str) -> None: ...
    tags: set[str]
    def is_tagged(self, tag: str) -> bool: ...

# ── Entity Subtypes ───────────────────────────────────────────────────

class ArmorStand(Entity):
    @property
    def small(self) -> bool: ...
    @small.setter
    def small(self, value: bool) -> None: ...
    @property
    def visible(self) -> bool: ...
    @visible.setter
    def visible(self, value: bool) -> None: ...
    @property
    def arms(self) -> bool: ...
    @arms.setter
    def arms(self, value: bool) -> None: ...
    @property
    def base_plate(self) -> bool: ...
    @base_plate.setter
    def base_plate(self, value: bool) -> None: ...
    @property
    def marker(self) -> bool: ...
    @marker.setter
    def marker(self, value: bool) -> None: ...
    @property
    def head_pose(self) -> Any: ...
    @head_pose.setter
    def head_pose(self, pose: Any) -> None: ...
    @property
    def body_pose(self) -> Any: ...
    @body_pose.setter
    def body_pose(self, pose: Any) -> None: ...
    @property
    def left_arm_pose(self) -> Any: ...
    @left_arm_pose.setter
    def left_arm_pose(self, pose: Any) -> None: ...
    @property
    def right_arm_pose(self) -> Any: ...
    @right_arm_pose.setter
    def right_arm_pose(self, pose: Any) -> None: ...
    @property
    def left_leg_pose(self) -> Any: ...
    @left_leg_pose.setter
    def left_leg_pose(self, pose: Any) -> None: ...
    @property
    def right_leg_pose(self) -> Any: ...
    @right_leg_pose.setter
    def right_leg_pose(self, pose: Any) -> None: ...

class Villager(Entity):
    @property
    def profession(self) -> str: ...
    @profession.setter
    def profession(self, value: str) -> None: ...
    @property
    def villager_type(self) -> str: ...
    @villager_type.setter
    def villager_type(self, value: str) -> None: ...
    @property
    def villager_level(self) -> int: ...
    @villager_level.setter
    def villager_level(self, value: int) -> None: ...
    @property
    def villager_experience(self) -> int: ...
    @villager_experience.setter
    def villager_experience(self, value: int) -> None: ...
    @property
    def recipes(self) -> list[dict]: ...
    @recipes.setter
    def recipes(self, value: list[dict]) -> None: ...
    @property
    def recipe_count(self) -> int: ...
    def add_recipe(self, result: dict, ingredients: list[dict], max_uses: int = 1,
                   experience_reward: bool = True, villager_experience: int = 0,
                   price_multiplier: float = 0.0, demand: int = 0, special_price: int = 0) -> None: ...
    def clear_recipes(self) -> None: ...

class ItemFrame(Entity):
    @property
    def item(self) -> Item | None: ...
    @item.setter
    def item(self, value: Item | None) -> None: ...
    @item.deleter
    def item(self) -> None: ...
    @property
    def rotation(self) -> Any: ...
    @rotation.setter
    def rotation(self, value: Any) -> None: ...
    @property
    def fixed(self) -> bool: ...
    @fixed.setter
    def fixed(self, value: bool) -> None: ...
    @property
    def item_drop_chance(self) -> float: ...
    @item_drop_chance.setter
    def item_drop_chance(self, value: float) -> None: ...

class FallingBlock(Entity):
    material: Any
    @property
    def drop_item(self) -> bool: ...
    @drop_item.setter
    def drop_item(self, value: bool) -> None: ...
    @property
    def can_hurt_entities(self) -> bool: ...
    @can_hurt_entities.setter
    def can_hurt_entities(self, value: bool) -> None: ...
    @property
    def damage_per_block(self) -> float: ...
    @damage_per_block.setter
    def damage_per_block(self, value: float) -> None: ...
    @property
    def max_damage(self) -> int: ...
    @max_damage.setter
    def max_damage(self, value: int) -> None: ...

class AreaEffectCloud(Entity):
    @property
    def radius(self) -> float: ...
    @radius.setter
    def radius(self, value: float) -> None: ...
    @property
    def color(self) -> Any: ...
    @color.setter
    def color(self, value: Any) -> None: ...
    @property
    def duration(self) -> int: ...
    @duration.setter
    def duration(self, value: int) -> None: ...
    @property
    def wait_time(self) -> int: ...
    @wait_time.setter
    def wait_time(self, value: int) -> None: ...
    @property
    def radius_on_use(self) -> float: ...
    @radius_on_use.setter
    def radius_on_use(self, value: float) -> None: ...
    @property
    def radius_per_tick(self) -> float: ...
    @radius_per_tick.setter
    def radius_per_tick(self, value: float) -> None: ...
    @property
    def particle(self) -> Any: ...
    @particle.setter
    def particle(self, value: Any) -> None: ...

# ── Player ────────────────────────────────────────────────────────────

class Player(Entity):
    name: str
    uuid: str
    location: Location
    world: World
    game_mode: GameMode
    health: float
    food_level: int
    inventory: Inventory
    held_item: Item
    selected_slot: int
    scoreboard: Scoreboard
    is_op: bool
    permission_groups: list[str]
    primary_group: str | None
    effects: list[Effect]
    attack_cooldown: float
    locale: str
    ping: int
    client_brand: str

    @property
    def tab_list_header(self) -> str: ...
    @tab_list_header.setter
    def tab_list_header(self, header: str) -> None: ...
    @property
    def tab_list_footer(self) -> str: ...
    @tab_list_footer.setter
    def tab_list_footer(self, footer: str) -> None: ...
    @property
    def tab_list_name(self) -> str: ...
    @tab_list_name.setter
    def tab_list_name(self, name: str) -> None: ...
    @property
    def level(self) -> int: ...
    @level.setter
    def level(self, level: int) -> None: ...
    @property
    def exp(self) -> float: ...
    @exp.setter
    def exp(self, exp: float) -> None: ...
    @property
    def is_flying(self) -> bool: ...
    @is_flying.setter
    def is_flying(self, value: bool) -> None: ...
    @property
    def is_sneaking(self) -> bool: ...
    @is_sneaking.setter
    def is_sneaking(self, value: bool) -> None: ...
    @property
    def is_sprinting(self) -> bool: ...
    @is_sprinting.setter
    def is_sprinting(self, value: bool) -> None: ...
    @property
    def absorption(self) -> float: ...
    @absorption.setter
    def absorption(self, value: float) -> None: ...
    @property
    def saturation(self) -> float: ...
    @saturation.setter
    def saturation(self, value: float) -> None: ...
    @property
    def exhaustion(self) -> float: ...
    @exhaustion.setter
    def exhaustion(self, value: float) -> None: ...
    @property
    def allow_flight(self) -> bool: ...
    @allow_flight.setter
    def allow_flight(self, value: bool) -> None: ...
    @property
    def max_health(self) -> float: ...
    @max_health.setter
    def max_health(self, value: float) -> None: ...
    @property
    def bed_spawn_location(self) -> Location | None: ...
    @bed_spawn_location.setter
    def bed_spawn_location(self, location: Location | None) -> None: ...
    @bed_spawn_location.deleter
    def bed_spawn_location(self) -> None: ...
    @property
    def compass_target(self) -> Location: ...
    @compass_target.setter
    def compass_target(self, location: Location) -> None: ...

    def send_message(self, message: str) -> Awaitable[None]: ...
    def chat(self, message: str) -> Awaitable[None]: ...
    def kick(self, reason: str = "") -> Awaitable[None]: ...
    def teleport(self, location: Location) -> Awaitable[None]: ...
    def give_exp(self, amount: int) -> Awaitable[None]: ...
    def add_effect(self, effect: Effect) -> Awaitable[None]: ...
    def remove_effect(self, effect_type: EffectType) -> Awaitable[None]: ...
    def set_game_mode(self, mode: GameMode) -> Awaitable[None]: ...
    def set_scoreboard(self, scoreboard: Scoreboard) -> Awaitable[None]: ...
    def has_permission(self, permission: str) -> Awaitable[bool]: ...
    def set_op(self, value: bool) -> Awaitable[None]: ...
    def add_permission(self, permission: str, value: bool = True) -> Awaitable[bool]: ...
    def remove_permission(self, permission: str) -> Awaitable[bool]: ...
    def has_group(self, group: str) -> Awaitable[bool]: ...
    def add_group(self, group: str) -> Awaitable[bool]: ...
    def remove_group(self, group: str) -> Awaitable[bool]: ...
    def play_sound(self, sound: Sound | str, volume: float = 1.0, pitch: float = 1.0) -> Awaitable[None]: ...
    def send_action_bar(self, message: str) -> Awaitable[None]: ...
    def send_title(self, title: str, subtitle: str = "", fade_in: int = 10, stay: int = 70, fade_out: int = 20) -> Awaitable[None]: ...
    def set_tab_list_header_footer(self, header: str = "", footer: str = "") -> Awaitable[None]: ...
    def set_health(self, health: float) -> Awaitable[None]: ...
    def set_food_level(self, level: int) -> Awaitable[None]: ...
    def set_level(self, level: int) -> Awaitable[None]: ...
    def set_exp(self, exp: float) -> Awaitable[None]: ...
    def set_walk_speed(self, speed: float) -> Awaitable[None]: ...
    def set_fly_speed(self, speed: float) -> Awaitable[None]: ...
    def set_resource_pack(self, url: str, hash: str = "", prompt: str | None = None, required: bool = False) -> Awaitable[None]: ...
    def hide_player(self, other: Player) -> Awaitable[None]: ...
    def show_player(self, other: Player) -> Awaitable[None]: ...
    def can_see(self, other: Player) -> bool: ...
    def open_book(self, item: Item) -> Awaitable[None]: ...
    def send_block_change(self, location: Location, material: str) -> Awaitable[None]: ...
    def send_particle(self, particle: str, location: Location, count: int = 1, offset_x: float = 0, offset_y: float = 0, offset_z: float = 0, extra: float = 0) -> Awaitable[None]: ...
    def get_cooldown(self, material: str) -> int: ...
    def set_cooldown(self, material: str, ticks: int) -> Awaitable[None]: ...
    def has_cooldown(self, material: str) -> bool: ...
    def get_statistic(self, stat: str, material_or_entity: str | None = None) -> int: ...
    def set_statistic(self, stat: str, value: int, material_or_entity: str | None = None) -> Awaitable[None]: ...
    def get_persistent_data(self) -> dict: ...
    def set_persistent_data(self, key: str, value: str) -> Awaitable[None]: ...
    def remove_persistent_data(self, key: str) -> Awaitable[None]: ...
    def has_persistent_data(self, key: str) -> bool: ...

    def freeze(self) -> None: ...
    def unfreeze(self) -> None: ...
    is_frozen: bool
    def vanish(self) -> None: ...
    def unvanish(self) -> None: ...
    is_vanished: bool

    # Extension integration (from player_data module)
    balance: float
    def deposit(self, amount: float) -> None: ...
    def withdraw(self, amount: float) -> None: ...
    @property
    def mana(self) -> float: ...
    @mana.setter
    def mana(self, value: float) -> None: ...
    xp: float
    player_level: int

# ── World ─────────────────────────────────────────────────────────────

class World(ProxyBase):
    def __init__(self, name: str | None = None) -> None: ...
    name: str
    uuid: str
    environment: Any
    entities: list[Entity]
    players: list[Player]
    seed: int
    game_rules: dict

    @property
    def time(self) -> int: ...
    @time.setter
    def time(self, time: int) -> None: ...
    @property
    def world_time(self) -> WorldTime: ...
    @property
    def difficulty(self) -> Difficulty: ...
    @difficulty.setter
    def difficulty(self, difficulty: Difficulty) -> None: ...
    @property
    def spawn_location(self) -> Location: ...
    @spawn_location.setter
    def spawn_location(self, location: Location) -> None: ...
    @property
    def full_time(self) -> int: ...
    @full_time.setter
    def full_time(self, time: int) -> None: ...
    @property
    def has_storm(self) -> bool: ...
    @has_storm.setter
    def has_storm(self, value: bool) -> None: ...
    @property
    def is_thundering(self) -> bool: ...
    @is_thundering.setter
    def is_thundering(self, value: bool) -> None: ...
    @property
    def weather_duration(self) -> int: ...
    @weather_duration.setter
    def weather_duration(self, ticks: int) -> None: ...
    @property
    def thunder_duration(self) -> int: ...
    @thunder_duration.setter
    def thunder_duration(self, ticks: int) -> None: ...
    @property
    def pvp(self) -> bool: ...
    @pvp.setter
    def pvp(self, value: bool) -> None: ...
    @property
    def world_border(self) -> dict: ...
    @world_border.setter
    def world_border(self, settings: dict) -> None: ...

    def block_at(self, x: int, y: int, z: int) -> Awaitable[Block]: ...
    def spawn_entity(self, location: Location, entity_type: EntityType | str, **kwargs: Any) -> Awaitable[Entity]: ...
    def chunk_at(self, x: int, z: int) -> Awaitable[Chunk]: ...
    def spawn(self, location: Location, entity_cls: type | EntityType | str, **kwargs: Any) -> Awaitable[Entity]: ...
    def at_time(self, time: WorldTime | int) -> Callable[..., Any]: ...
    def spawn_particle(self, particle: Particle, location: Location, count: int = 1, offset_x: float = 0, offset_y: float = 0, offset_z: float = 0, extra: float = 0) -> Awaitable[None]: ...
    def play_sound(self, location: Location, sound: Sound, volume: float = 1.0, pitch: float = 1.0) -> Awaitable[None]: ...
    def strike_lightning(self, location: Location) -> Awaitable[Entity]: ...
    def strike_lightning_effect(self, location: Location) -> Awaitable[None]: ...
    def __contains__(self, entity: Any) -> bool: ...

    # Region utilities
    def set_block(self, x: int, y: int, z: int, material: Material | str, apply_physics: bool = False) -> Awaitable[int]: ...
    def fill(self, pos1: Location | tuple | Vector, pos2: Location | tuple | Vector, material: Material | str, apply_physics: bool = False) -> Awaitable[int]: ...
    def replace(self, pos1: Location | tuple | Vector, pos2: Location | tuple | Vector, from_material: Material | str, to_material: Material | str) -> Awaitable[int]: ...
    def fill_sphere(self, center: Location | tuple | Vector, radius: float, material: Material | str, hollow: bool = False) -> Awaitable[int]: ...
    def fill_cylinder(self, center: Location | tuple | Vector, radius: float, height: int, material: Material | str, hollow: bool = False) -> Awaitable[int]: ...
    def fill_line(self, start: Location | tuple | Vector, end: Location | tuple | Vector, material: Material | str) -> Awaitable[int]: ...

    # Particle shapes
    def particle_line(self, start: Location | tuple | Vector, end: Location | tuple | Vector, particle: Particle | str, density: float = 4.0, offset_x: float = 0, offset_y: float = 0, offset_z: float = 0, extra: float = 0) -> Awaitable[int]: ...
    def particle_sphere(self, center: Location | tuple | Vector, radius: float, particle: Particle | str, density: float = 4.0, hollow: bool = True, offset_x: float = 0, offset_y: float = 0, offset_z: float = 0, extra: float = 0) -> Awaitable[int]: ...
    def particle_cube(self, pos1: Location | tuple | Vector, pos2: Location | tuple | Vector, particle: Particle | str, density: float = 4.0, hollow: bool = True, offset_x: float = 0, offset_y: float = 0, offset_z: float = 0, extra: float = 0) -> Awaitable[int]: ...
    def particle_ring(self, center: Location | tuple | Vector, radius: float, particle: Particle | str, density: float = 4.0, offset_x: float = 0, offset_y: float = 0, offset_z: float = 0, extra: float = 0) -> Awaitable[int]: ...

    # Spawn helpers
    def spawn_at_player(self, player: Player, entity_type: EntityType | str, offset: Vector | tuple | None = None, **kwargs: Any) -> Awaitable[Entity]: ...
    def spawn_projectile(self, shooter: Entity, entity_type: EntityType | str, velocity: Vector | tuple | None = None, **kwargs: Any) -> Awaitable[Entity]: ...
    def spawn_with_nbt(self, location: Location, entity_type: EntityType | str, nbt: str, **kwargs: Any) -> Awaitable[Entity]: ...
    def create_explosion(self, location: Location, power: float = 4.0, fire: bool = False) -> Awaitable[None]: ...
    def entities_near(self, location: Location, radius: float) -> list[Entity]: ...
    def blocks_near(self, location: Location, radius: int) -> list[Block]: ...

    # Game rules
    def get_game_rule(self, rule: str) -> Any: ...
    def set_game_rule(self, rule: str, value: Any) -> Awaitable[None]: ...

    # Terrain / entity queries
    def get_highest_block_at(self, x: int, z: int) -> Block: ...
    def generate_tree(self, location: Location, tree_type: str) -> bool: ...
    def get_nearby_entities(self, location: Location, dx: float, dy: float, dz: float) -> list[Entity]: ...
    def get_chunk_at_async(self, x: int, z: int) -> Awaitable[Chunk]: ...
    def batch_spawn(self, specs: list[dict]) -> list[Entity]: ...
    def ray_trace(self, start: Location, direction: Any, max_distance: float) -> dict | None: ...
    def find_entities(self, location: Location, radius: float, predicate: Callable[[Entity], bool] | None = None, entity_type: str | None = None) -> list[Entity]: ...

    # Async world edit
    async def async_fill(self, x1: int, y1: int, z1: int, x2: int, y2: int, z2: int, material: str, blocks_per_tick: int = 256) -> None: ...
    async def async_replace(self, x1: int, y1: int, z1: int, x2: int, y2: int, z2: int, from_material: str, to_material: str, blocks_per_tick: int = 256) -> None: ...

# ── Firework ──────────────────────────────────────────────────────────

class Firework:
    @staticmethod
    def launch(location: Location, effects: list | None = None, power: int = 1) -> Awaitable[Entity]: ...

class FireworkEffect:
    def __init__(self, shape: str = "BALL") -> None: ...
    def colors(self, *colors: Any) -> FireworkEffect: ...
    def fade(self, *colors: Any) -> FireworkEffect: ...
    def flicker(self, value: bool = True) -> FireworkEffect: ...
    def trail(self, value: bool = True) -> FireworkEffect: ...

# ── Location ──────────────────────────────────────────────────────────

class Dimension: ...

class Location(ProxyBase):
    def __init__(self, x: float = 0.0, y: float = 0.0, z: float = 0.0, world: World | str | None = None, yaw: float = 0.0, pitch: float = 0.0) -> None: ...
    x: float
    y: float
    z: float
    yaw: float
    pitch: float
    world: World
    def add(self, x: float, y: float, z: float) -> Location: ...
    def clone(self) -> Location: ...
    def distance(self, other: Location) -> float: ...
    def distance_squared(self, other: Location) -> float: ...
    def normalize(self) -> Location: ...
    def midpoint(self, other: Location) -> Location: ...
    def __add__(self, other: Location | Vector) -> Location: ...
    def __sub__(self, other: Location | Vector) -> Location: ...
    def __mul__(self, scalar: int | float) -> Location: ...
    def __truediv__(self, scalar: int | float) -> Location: ...
    def __getitem__(self, index: int) -> float: ...
    def __iter__(self) -> Iterator[float]: ...
    def __len__(self) -> int: ...

# ── Block ─────────────────────────────────────────────────────────────

class Block(ProxyBase):
    def __init__(self, world: World | str | None = None, x: int | None = None, y: int | None = None, z: int | None = None, material: Material | str | None = None) -> None: ...
    @classmethod
    def create(cls, location: Location, material: Material | str) -> Awaitable[Block]: ...
    x: int
    y: int
    z: int
    type: Material
    location: Location
    world: World
    is_solid: bool
    light_level: int
    is_container: bool
    state_type: str
    hardness: float
    blast_resistance: float
    is_passable: bool
    is_liquid: bool
    drops: list
    furnace_cook_time_total: int

    @property
    def data(self) -> Any: ...
    @data.setter
    def data(self, data: Any) -> None: ...
    @property
    def biome(self) -> Biome: ...
    @biome.setter
    def biome(self, biome: Biome) -> None: ...
    @property
    def sign_lines(self) -> list[str]: ...
    @sign_lines.setter
    def sign_lines(self, lines: list[str]) -> None: ...
    @property
    def sign_back_lines(self) -> list[str]: ...
    @sign_back_lines.setter
    def sign_back_lines(self, lines: list[str]) -> None: ...
    @property
    def is_sign_glowing(self) -> bool: ...
    @is_sign_glowing.setter
    def is_sign_glowing(self, glowing: bool) -> None: ...
    @property
    def furnace_burn_time(self) -> int: ...
    @furnace_burn_time.setter
    def furnace_burn_time(self, ticks: int) -> None: ...
    @property
    def furnace_cook_time(self) -> int: ...
    @furnace_cook_time.setter
    def furnace_cook_time(self, ticks: int) -> None: ...
    @property
    def inventory(self) -> Inventory: ...

    def break_naturally(self) -> Awaitable[None]: ...
    def set_type(self, material: Material) -> Awaitable[None]: ...
    def set_sign_line(self, index: int, text: str) -> Awaitable[None]: ...
    def set_sign_back_line(self, index: int, text: str) -> Awaitable[None]: ...
    def get_drops(self, tool: Item | None = None) -> list: ...
    def get_persistent_data(self) -> dict: ...
    def set_persistent_data(self, key: str, value: str) -> Awaitable[None]: ...
    def remove_persistent_data(self, key: str) -> Awaitable[None]: ...

class BlockSnapshot:
    def __init__(self, world: World, blocks: list[dict]) -> None: ...
    @classmethod
    def capture(cls, world: World, x1: int, y1: int, z1: int, x2: int, y2: int, z2: int) -> BlockSnapshot: ...
    blocks: list[dict]
    async def restore(self, blocks_per_tick: int = 256) -> None: ...
    def __len__(self) -> int: ...

# ── Chunk ─────────────────────────────────────────────────────────────

class Chunk(ProxyBase):
    def __init__(self, world: World | str | None = None, x: int | None = None, z: int | None = None) -> None: ...
    x: int
    z: int
    world: World
    def load(self) -> Awaitable[bool]: ...
    def unload(self) -> Awaitable[bool]: ...
    is_loaded: bool

# ── Inventory ─────────────────────────────────────────────────────────

class Inventory(ProxyBase):
    def __init__(self, size: int = 9, title: str = "", contents: list[Item] | None = None) -> None: ...
    size: int
    contents: list[Item]
    holder: Any
    title: str
    viewers: list
    type: Any
    first_empty: int
    def open(self, player: Player) -> Awaitable[Any]: ...
    def add_item(self, item: Item) -> Awaitable[Any]: ...
    def remove_item(self, item: Item) -> Awaitable[Any]: ...
    def clear(self) -> Awaitable[None]: ...
    def close(self, player: Player | None = None) -> Awaitable[Any]: ...
    def get_item(self, slot: int) -> Awaitable[Item]: ...
    def set_item(self, slot: int, item: Item) -> Awaitable[None]: ...
    def contains(self, material: Material, amount: int = 1) -> Awaitable[bool]: ...
    def __getitem__(self, slot: int) -> Any: ...
    def __setitem__(self, slot: int, item: Any) -> None: ...
    def __iter__(self) -> Iterator: ...
    def __len__(self) -> int: ...
    async def __aenter__(self) -> Inventory: ...
    async def __aexit__(self, *args: Any) -> None: ...

# ── Item ──────────────────────────────────────────────────────────────

class Item(ProxyBase):
    def __init__(self, material: Material | str | None = None, amount: int = 1, name: str | None = None, lore: list[str] | None = None, custom_model_data: int | None = None, attributes: list[dict[str, Any]] | None = None, nbt: dict[str, Any] | None = None) -> None: ...
    @classmethod
    def drop(cls, location: Location, amount: int = 1, material: Material | str | None = None, **kwargs: Any) -> Awaitable[Entity]: ...
    @classmethod
    def give(cls, player: Player, material: Material | str | None = None, amount: int = 1, **kwargs: Any) -> Awaitable[Any]: ...
    type: Material
    max_stack_size: int
    enchantments: dict[str, int]
    max_durability: int

    @property
    def amount(self) -> int: ...
    @amount.setter
    def amount(self, value: int) -> None: ...
    @property
    def name(self) -> str | None: ...
    @name.setter
    def name(self, name: str) -> None: ...
    @property
    def lore(self) -> list[str]: ...
    @lore.setter
    def lore(self, lore: list[str]) -> None: ...
    @property
    def custom_model_data(self) -> int | None: ...
    @custom_model_data.setter
    def custom_model_data(self, value: int) -> None: ...
    @property
    def attributes(self) -> list[dict[str, Any]]: ...
    @attributes.setter
    def attributes(self, attributes: list[dict[str, Any]]) -> None: ...
    @property
    def nbt(self) -> dict[str, Any]: ...
    @nbt.setter
    def nbt(self, nbt: dict[str, Any]) -> None: ...
    @property
    def durability(self) -> int: ...
    @durability.setter
    def durability(self, value: int) -> None: ...
    @property
    def is_unbreakable(self) -> bool: ...
    @is_unbreakable.setter
    def is_unbreakable(self, value: bool) -> None: ...
    @property
    def item_flags(self) -> list[str]: ...
    @item_flags.setter
    def item_flags(self, flags: list[str]) -> None: ...

    def set_name(self, name: str) -> Awaitable[None]: ...
    def set_lore(self, lore: list[str]) -> Awaitable[None]: ...
    def clone(self) -> Awaitable[Item]: ...
    def is_similar(self, other: Item) -> Awaitable[bool]: ...
    def add_enchantment(self, enchantment: str, level: int = 1) -> Awaitable[None]: ...
    def remove_enchantment(self, enchantment: str) -> Awaitable[None]: ...
    def add_item_flags(self, *flags: str) -> Awaitable[None]: ...
    def remove_item_flags(self, *flags: str) -> Awaitable[None]: ...

class ItemBuilder:
    def __init__(self, material: Material | str) -> None: ...
    def amount(self, n: int) -> ItemBuilder: ...
    def name(self, n: str) -> ItemBuilder: ...
    def lore(self, *lines: str) -> ItemBuilder: ...
    def add_lore(self, line: str) -> ItemBuilder: ...
    def enchant(self, enchantment: str, level: int = 1) -> ItemBuilder: ...
    def unbreakable(self, value: bool = True) -> ItemBuilder: ...
    def glow(self, value: bool = True) -> ItemBuilder: ...
    def custom_model_data(self, value: int) -> ItemBuilder: ...
    def attributes(self, attrs: list[dict[str, Any]]) -> ItemBuilder: ...
    def add_attribute(self, attribute: str, amount: float, operation: str = "ADD_NUMBER") -> ItemBuilder: ...
    def nbt(self, data: dict[str, Any]) -> ItemBuilder: ...
    def flag(self, *flags: str) -> ItemBuilder: ...
    def build(self) -> Item: ...
    @classmethod
    def from_item(cls, item: Item) -> ItemBuilder: ...

class BookBuilder:
    def __init__(self, title: str = "Book", author: str = "Server") -> None: ...
    def title(self, title: str) -> BookBuilder: ...
    def author(self, author: str) -> BookBuilder: ...
    def page(self, content: str) -> BookBuilder: ...
    def pages(self, *contents: str) -> BookBuilder: ...
    def build(self) -> Item: ...

class TextComponent:
    def __init__(self, text: str = "") -> None: ...
    def text(self, content: str) -> TextComponent: ...
    def bold(self, content: str) -> TextComponent: ...
    def italic(self, content: str) -> TextComponent: ...
    def underlined(self, content: str) -> TextComponent: ...
    def strikethrough(self, content: str) -> TextComponent: ...
    def obfuscated(self, content: str) -> TextComponent: ...
    def color(self, color: str, content: str) -> TextComponent: ...
    def gradient(self, colors: list[str], content: str) -> TextComponent: ...
    def click_url(self, url: str, content: str = "") -> TextComponent: ...
    def click_command(self, command: str, content: str = "") -> TextComponent: ...
    def click_suggest(self, command: str, content: str = "") -> TextComponent: ...
    def click_copy(self, text: str, content: str = "") -> TextComponent: ...
    def hover(self, hover_text: str, content: str = "") -> TextComponent: ...
    def newline(self) -> TextComponent: ...
    def __str__(self) -> str: ...
    def __repr__(self) -> str: ...
    def __add__(self, other: Any) -> TextComponent: ...

# ── Effect / Attribute / Potion ───────────────────────────────────────

class Effect(ProxyBase):
    @classmethod
    def apply(cls, player: Player, effect_type: EffectType | str | None = None, duration: int = 0, amplifier: int = 0, ambient: bool = False, particles: bool = True, icon: bool = True) -> Awaitable[Any]: ...
    def __init__(self, effect_type: EffectType | str | None = None, duration: int = 0, amplifier: int = 0, ambient: bool = False, particles: bool = True, icon: bool = True) -> None: ...
    type: EffectType
    duration: int
    amplifier: int
    ambient: bool
    particles: bool
    icon: bool
    def with_duration(self, duration: int) -> Awaitable[Effect]: ...
    def with_amplifier(self, amplifier: int) -> Awaitable[Effect]: ...

class Attribute(ProxyBase):
    @classmethod
    def apply(cls, player: Player, attribute_type: AttributeType | str, base_value: float) -> Awaitable[Any]: ...
    attribute_type: AttributeType
    value: float
    base_value: float
    def set_base_value(self, value: float) -> Awaitable[None]: ...

class Potion(ProxyBase):
    @classmethod
    def apply(cls, player: Player, effect_type: EffectType | str | None = None, duration: int = 0, amplifier: int = 0, ambient: bool = False, particles: bool = True, icon: bool = True) -> Awaitable[Any]: ...
    type: Any
    level: int

# ── Recipe ────────────────────────────────────────────────────────────

class Recipe:
    @staticmethod
    def shaped(key: str, result: Material | str, shape: list, ingredients: dict, amount: int = 1) -> Awaitable[str]: ...
    @staticmethod
    def shapeless(key: str, result: Material | str, ingredients: list, amount: int = 1) -> Awaitable[str]: ...
    @staticmethod
    def furnace(key: str, input: Material | str, result: Material | str, experience: float = 0, cook_time: int = 200, amount: int = 1) -> Awaitable[str]: ...
    @staticmethod
    def remove(key: str) -> Awaitable[bool]: ...

# ── Vector ────────────────────────────────────────────────────────────

class Vector(ProxyBase):
    def __init__(self, x: float = 0.0, y: float = 0.0, z: float = 0.0) -> None: ...
    x: float
    y: float
    z: float
    def __add__(self, other: Vector | list | tuple) -> Vector: ...
    def __sub__(self, other: Vector | list | tuple) -> Vector: ...
    def __mul__(self, other: int | float | Vector | list | tuple) -> Vector: ...
    def __rmul__(self, other: int | float | Vector | list | tuple) -> Vector: ...

# ── BossBar ───────────────────────────────────────────────────────────

class BossBar(ProxyBase):
    @classmethod
    def create(cls, title: str, color: BarColor | None = None, style: BarStyle | None = None, players: list[Player] | None = None) -> BossBar: ...
    def add_player(self, player: Player) -> Awaitable[None]: ...
    def remove_player(self, player: Player) -> Awaitable[None]: ...
    @property
    def title(self) -> str: ...
    @title.setter
    def title(self, title: str) -> None: ...
    @property
    def progress(self) -> float: ...
    @progress.setter
    def progress(self, value: float) -> None: ...
    @property
    def color(self) -> BarColor: ...
    @color.setter
    def color(self, color: BarColor) -> None: ...
    @property
    def style(self) -> BarStyle: ...
    @style.setter
    def style(self, style: BarStyle) -> None: ...
    @property
    def visible(self) -> bool: ...
    @visible.setter
    def visible(self, value: bool) -> None: ...
    def set_title(self, title: str) -> Awaitable[None]: ...
    def set_progress(self, value: float) -> Awaitable[None]: ...
    def set_color(self, color: BarColor) -> Awaitable[None]: ...
    def set_style(self, style: BarStyle) -> Awaitable[None]: ...
    def set_visible(self, value: bool) -> Awaitable[None]: ...

# ── Scoreboard / Team / Objective ─────────────────────────────────────

class Scoreboard(ProxyBase):
    @classmethod
    def create(cls) -> Scoreboard: ...
    def register_objective(self, name: str, criteria: str, display_name: str = "") -> Objective: ...
    def get_team(self, name: str) -> Team: ...
    def register_team(self, name: str) -> Team: ...
    def get_objective(self, name: str) -> Objective: ...
    objectives: list[Objective]
    teams: list[Team]
    def clear_slot(self, slot: Any) -> Awaitable[None]: ...

class Team(ProxyBase):
    @classmethod
    def create(cls, name: str, scoreboard: Scoreboard | None = None) -> Team: ...
    def add_entry(self, entry: str) -> Awaitable[None]: ...
    def remove_entry(self, entry: str) -> Awaitable[None]: ...
    def set_prefix(self, prefix: str) -> Awaitable[None]: ...
    def set_suffix(self, suffix: str) -> Awaitable[None]: ...
    @property
    def color(self) -> Any: ...
    @color.setter
    def color(self, color: Any) -> None: ...
    entries: set[str]

class Objective(ProxyBase):
    @classmethod
    def create(cls, name: str, criteria: str, display_name: str = "", scoreboard: Scoreboard | None = None) -> Objective: ...
    def set_display_name(self, name: str) -> Awaitable[None]: ...
    def get_score(self, entry: str) -> Any: ...
    name: str
    criteria: str
    @property
    def display_slot(self) -> Any: ...
    @display_slot.setter
    def display_slot(self, slot: Any) -> None: ...

# ── Advancement ───────────────────────────────────────────────────────

class Advancement(ProxyBase):
    @classmethod
    def grant(cls, player: Player, key: str) -> Awaitable[AdvancementProgress]: ...
    @classmethod
    def revoke(cls, player: Player, key: str) -> Awaitable[AdvancementProgress]: ...
    key: Any

class AdvancementProgress(ProxyBase):
    is_done: bool
    def award_criteria(self, name: str) -> Awaitable[bool]: ...
    def revoke_criteria(self, name: str) -> Awaitable[bool]: ...
    remaining_criteria: set[str]
    awarded_criteria: set[str]

# ── Helpers (from helpers.py) ─────────────────────────────────────────

class ConsolePlayer:
    fields: dict[str, Any]
    name: str
    uuid: str
    def is_op(self) -> Awaitable[bool]: ...
    def has_permission(self, permission: str) -> Awaitable[bool]: ...
    def send_message(self, message: str) -> Awaitable[None]: ...
    def play_sound(self, sound: Any, volume: float = 1.0, pitch: float = 1.0) -> Awaitable[None]: ...
    def kick(self, reason: str = "") -> Awaitable[None]: ...

class Sidebar:
    MAX_LINES: int
    def __init__(self, title: str = "") -> None: ...
    def __setitem__(self, slot: int, text: str) -> None: ...
    def __getitem__(self, slot: int) -> str: ...
    def __delitem__(self, slot: int) -> None: ...
    def show(self, player: Player) -> None: ...
    title: str

class Config:
    def __init__(self, name: str | None = None, defaults: dict[str, Any] | None = None, format: str = "toml") -> None: ...
    def reload(self) -> None: ...
    def save(self) -> None: ...
    def get(self, path: str, default: Any = None) -> Any: ...
    def get_int(self, path: str, default: int = 0) -> int: ...
    def get_float(self, path: str, default: float = 0.0) -> float: ...
    def get_bool(self, path: str, default: bool = False) -> bool: ...
    def get_list(self, path: str, default: list[Any] | None = None) -> list[Any]: ...
    def set(self, path: str, value: Any) -> None: ...
    def delete(self, path: str) -> bool: ...
    def __getitem__(self, key: str) -> Any: ...
    def __setitem__(self, key: str, value: Any) -> None: ...
    def __contains__(self, key: str) -> bool: ...
    data: dict[str, Any]
    path: str

class State:
    def __init__(self, name: str | None = None) -> None: ...
    def load(self) -> None: ...
    def save(self) -> None: ...
    def __getitem__(self, key: str) -> Any: ...
    def __setitem__(self, key: str, value: Any) -> None: ...
    def __delitem__(self, key: str) -> None: ...
    def __contains__(self, key: str) -> bool: ...
    def get(self, key: str, default: Any = None) -> Any: ...
    def keys(self) -> Any: ...
    def values(self) -> Any: ...
    def items(self) -> Any: ...
    def clear(self) -> None: ...
    def update(self, data: dict) -> None: ...
    data: dict[str, Any]
    path: str

class Cooldown:
    seconds: float
    on_expire: Callable[[Player], Any] | None
    def __init__(self, seconds: float = 1.0, on_expire: Callable[[Player], Any] | None = None) -> None: ...
    def check(self, player: Player) -> bool: ...
    def remaining(self, player: Player) -> float: ...
    def reset(self, player: Player) -> None: ...

class Hologram:
    def __init__(self, location: Location, *lines: str, billboard: str = "CENTER") -> None: ...
    def __setitem__(self, index: int, text: str) -> None: ...
    def __getitem__(self, index: int) -> str: ...
    def __delitem__(self, index: int) -> None: ...
    def __len__(self) -> int: ...
    def append(self, text: str) -> None: ...
    def teleport(self, location: Location) -> None: ...
    def remove(self) -> None: ...
    @property
    def billboard(self) -> str: ...
    @billboard.setter
    def billboard(self, value: str) -> None: ...
    @property
    def see_through(self) -> bool: ...
    @see_through.setter
    def see_through(self, value: bool) -> None: ...
    @property
    def shadowed(self) -> bool: ...
    @shadowed.setter
    def shadowed(self, value: bool) -> None: ...
    @property
    def alignment(self) -> str: ...
    @alignment.setter
    def alignment(self, value: str) -> None: ...
    @property
    def line_width(self) -> int: ...
    @line_width.setter
    def line_width(self, value: int) -> None: ...
    @property
    def background(self) -> int | None: ...
    @background.setter
    def background(self, value: int | None) -> None: ...

class ActionBarDisplay:
    def __init__(self) -> None: ...
    def __setitem__(self, player: Player, text: str) -> None: ...
    def __getitem__(self, player: Player) -> str: ...
    def __delitem__(self, player: Player) -> None: ...

class BossBarDisplay:
    def __init__(self, title: str = "", color: str = "PINK", style: str = "SOLID") -> None: ...
    def show(self, player: Player) -> None: ...
    def hide(self, player: Player) -> None: ...
    @property
    def text(self) -> str: ...
    @text.setter
    def text(self, value: str) -> None: ...
    @property
    def color(self) -> BarColor: ...
    @color.setter
    def color(self, value: str) -> None: ...
    @property
    def style(self) -> BarStyle: ...
    @style.setter
    def style(self, value: str) -> None: ...
    @property
    def value(self) -> float: ...
    @value.setter
    def value(self, v: float) -> None: ...
    @property
    def max(self) -> float: ...
    @max.setter
    def max(self, v: float) -> None: ...
    @property
    def progress(self) -> float: ...
    @progress.setter
    def progress(self, v: float) -> None: ...
    @property
    def visible(self) -> bool: ...
    @visible.setter
    def visible(self, v: bool) -> None: ...
    def link_to(self, source: Any, player: Player) -> None: ...

class BlockDisplay:
    def __init__(self, location: Location, block_type: str, billboard: str = "FIXED") -> None: ...
    def teleport(self, location: Location) -> None: ...
    def remove(self) -> None: ...
    @property
    def billboard(self) -> str: ...
    @billboard.setter
    def billboard(self, value: str) -> None: ...

class ItemDisplay:
    def __init__(self, location: Location, item: Item | str, billboard: str = "FIXED") -> None: ...
    def teleport(self, location: Location) -> None: ...
    def remove(self) -> None: ...
    @property
    def billboard(self) -> str: ...
    @billboard.setter
    def billboard(self, value: str) -> None: ...

class MenuItem:
    item: Item
    on_click: Callable[[Player, Event], Any] | None
    def __init__(self, item: Item | str, on_click: Callable[[Player, Event], Any] | None = None) -> None: ...

class Menu:
    def __init__(self, title: str = "", rows: int = 3) -> None: ...
    def __setitem__(self, slot: int, menu_item: MenuItem) -> None: ...
    def __getitem__(self, slot: int) -> MenuItem | None: ...
    def __delitem__(self, slot: int) -> None: ...
    def fill_border(self, item: Item) -> None: ...
    def open(self, player: Player) -> None: ...
    title: str
    rows: int

class Paginator(Menu):
    def __init__(self, title: str = "", rows: int = 3, items: list[MenuItem] | None = None) -> None: ...
    page_count: int
    def add_page(self) -> int: ...
    def set_page_item(self, page: int, slot: int, menu_item: MenuItem) -> None: ...
    def open(self, player: Player, page: int = 0) -> None: ...

# ── Server / Chat / Reflect ──────────────────────────────────────────

class Server(ProxyBase):
    def broadcast(self, message: str) -> Awaitable[None]: ...
    def execute(self, command: str) -> Awaitable[bool]: ...
    players: list[Player]
    worlds: list[World]
    def world(self, name: str) -> Awaitable[World]: ...
    scoreboard_manager: Any
    def create_boss_bar(self, title: str, color: BarColor, style: BarStyle) -> Awaitable[BossBar]: ...
    boss_bars: list[BossBar]
    def get_advancement(self, key: str) -> Awaitable[Advancement]: ...
    plugin_manager: Any
    scheduler: Any
    def after(self, ticks: int = 1, after: Callable[[], Any] | None = None) -> Awaitable[None]: ...
    def frame(self) -> Any: ...
    def atomic(self) -> Any: ...
    def flush(self) -> Awaitable[None]: ...
    name: str
    version: str
    motd: str
    max_players: int
    tps: list[float]
    mspt: float
    last_tick_time: float
    queue_len: int

    # StructureManager
    def save_structure(self, name: str, world: World | str, x1: int, y1: int, z1: int, x2: int, y2: int, z2: int) -> Awaitable[str]: ...
    def load_structure(self, name: str, world: World | str, x: float, y: float, z: float, include_entities: bool = False) -> Awaitable[str]: ...
    def delete_structure(self, name: str) -> Awaitable[Any]: ...
    structures: list[str]

    # WorldCreator
    def create_world(self, name: str, *, environment: str = "NORMAL", world_type: str = "NORMAL", seed: int | None = None, generate_structures: bool = True) -> Awaitable[World]: ...
    def unload_world(self, name: str) -> Awaitable[bool]: ...

class ChatFacade(ProxyBase):
    def broadcast(self, message: str) -> Awaitable[None]: ...

class ReflectFacade(ProxyBase):
    def clazz(self, name: str) -> Awaitable[Any]: ...

# ── Module-level singletons ──────────────────────────────────────────

server: Server
chat: ChatFacade
reflect: ReflectFacade
_connection: BridgeConnection

# ── Module-level functions ────────────────────────────────────────────

def fire_event(event_name: str, data: dict | None = None) -> None: ...

# Decorators (from decorators.py)
def event(func: Callable[[Event], Any] | None = None, *, once_per_tick: bool = False, priority: str = "NORMAL", throttle_ms: int = 0) -> Callable[..., Any]: ...
def task(func: Callable[[], Any] | None = None, *, interval: int = 20, delay: int = 0) -> Callable[..., Any]: ...
def command(description: str | None = None, *, name: str | None = None, permission: str | None = None, tab_complete: dict | None = None) -> Callable[..., Any]: ...
def preserve(func: Callable[[], Any]) -> Callable[[], Any]: ...

# Packet API (from api.py)
def has_packet_api() -> BridgeCall: ...
def on_packet_send(packet_type: str) -> Callable[..., Any]: ...
def on_packet_receive(packet_type: str) -> Callable[..., Any]: ...
def send_packet(player: Any, packet_type: str, fields: dict[str, Any] | None = None) -> BridgeCall: ...
def remove_packet_listener(key: str) -> BridgeCall: ...

# Inter-script communication (from api.py)
def script_send(target: str, data: Any = None) -> None: ...
def on_script_message(handler: Callable[[Any], Any]) -> Callable[[Any], Any]: ...
def get_scripts() -> BridgeCall: ...

# Raycast (from api.py)
async def raycast(
    world: World | str,
    start: Vector | tuple[float, float, float],
    direction: tuple[float, float],
    max_distance: float = 64.0,
    ray_size: float = 0.2,
    include_entities: bool = True,
    include_blocks: bool = True,
    ignore_passable: bool = True,
) -> RaycastResult | None: ...

# ── Internal bootstrap ────────────────────────────────────────────────
def _bootstrap(script_path: str) -> None: ...
