Меню, HUD, сообщения

Руководство: Меню, HUD и чат.

Menu

Menu(
    title: str | Callable[[Player], str],
    *,
    per_page: int = 7,
    exit: bool = True,
    timeout: float | None = None,
)

Меню со страницами: клавиши 1–7 — пункты, 8/9 — листать, 0 — выход.

Теги цвета в текстах: !y жёлтый, !w белый, !r красный, !d серый, !R — выравнивание к правому краю.

Параметры

• title — заголовок (строка или функция от игрока).
• per_page — пунктов на странице, 1–7.
• exit — показывать «0. Выход».
• timeout — секунд до автозакрытия (None — висит до выбора).

Пример

shop = Menu("Магазин")

@shop.item("Броня !y($1000)", enabled=lambda p: p.money >= 1000)
def armor(player: Player) -> None:
    player.money -= 1000
    player.armor = 100

shop.show(player)

item

item(
    title: str | Callable[[Player], str],
    *,
    visible: Callable[[Player], bool] | None = None,
    enabled: Callable[[Player], bool] | None = None,
    data: Any = None,
) -> ItemDecorator

Пункт меню-декоратор; функция вызывается с выбравшим игроком.

Параметры

• title — текст пункта или функция от игрока.
• visible — показывать ли пункт этому игроку.
• enabled — активен ли пункт (неактивный — серый).
• data — любые данные пункта (item.data).

Пример

@shop.item(lambda p: f"Ваш ник: !y{p.name}", visible=lambda p: p.alive)
def whoami(player: Player) -> None: ...

add

add(
    title: str | Callable[[Player], str],
    callback: Callable[[Player], Any] | None = None,
    *,
    visible: Callable[[Player], bool] | None = None,
    enabled: Callable[[Player], bool] | None = None,
    data: Any = None,
) -> MenuItem

Добавить пункт без декоратора; возвращает MenuItem.

Пример

for n, weapon in enumerate(weapons):
    menu.add(weapon.title, lambda p, w=weapon: give(p, w), data=n)

show

show(player: Player, *, page: int = 0) -> None

Показать меню игроку (page — с нуля); старое меню закроется.

close

close(player: Player) -> None

Закрыть меню у игрока, если показано именно оно.

choose

choose(player: Player, *, timeout: float | None = None) -> MenuItem | None

Показать меню и дождаться выбора.

Возвращает

Выбранный MenuItem или None: выход, тайм-аут, другое меню, игрок вышел.

Пример

item = await menu.choose(player, timeout=10)
if item is not None:
    player.print(f"Выбрано: {item.data}")

ask

ask(
    player: Player, title: str, options: Sequence[str], *, timeout: float | None = None
) -> int | None

Быстрый вопрос с вариантами: номер выбранного (с 0) или None.

Пример

choice = await Menu.ask(player, "Карта?", ["de_dust2", "de_inferno"], timeout=15)
if choice is not None:
    server.change_level(maps[choice])

MenuItem

MenuItem(
    title: str | Callable[[Player], str],
    callback: Callable[[Player], Any] | None = None,
    visible: Callable[[Player], bool] | None = None,
    enabled: Callable[[Player], bool] | None = None,
    data: Any = None,
)

Пункт меню: текст (или функция от игрока), обработчик, видимость, доступность, данные.

label

label(player: Player) -> str

Текст пункта для этого игрока.

Hud

Hud(
    *,
    x: float = -1.0,
    y: float = 0.35,
    color: Sequence[int] = (255, 255, 255),
    effect: int = 0,
    fade_in: float = 0.1,
    fade_out: float = 0.2,
    hold: float = 3.0,
    fx_time: float = 0.0,
    color2: Sequence[int] = (255, 255, 255),
    channel: int | None = None,
)

Обычный HUD-текст (TE_TEXTMESSAGE): до 479 байт, 4 канала.

Сообщения одного канала заменяют друг друга; без channel каждый Hud берёт следующий из 1–4.

Параметры

• x — позиция по горизонтали 0–1; -1 — по центру.
• y — позиция по вертикали 0–1; -1 — по центру.
• color — цвет (r, g, b) или (r, g, b, a).
• effect — 0 — появление, 1 — мерцание, 2 — печать по буквам.
• fade_in — секунд появления.
• fade_out — секунд исчезновения.
• hold — секунд на экране.
• fx_time — время эффекта 2 на букву.
• color2 — цвет подсветки для эффекта 2.
• channel — канал 1–4 (None — следующий свободный по кругу).

Пример

info = Hud(y=0.25, color=(0, 200, 255), hold=4)
info.show(player, f"Здоровье: {player.health}")

clear

clear(player: Player | None = None) -> None

Стереть сообщение этого канала у игрока (или у всех).

DirectorHud

DirectorHud(
    *,
    x: float = -1.0,
    y: float = 0.35,
    color: Sequence[int] = (255, 255, 255),
    effect: int = 0,
    fade_in: float = 0.1,
    fade_out: float = 0.2,
    hold: float = 3.0,
    fx_time: float = 0.0,
)

Крупный HUD (director message, «DHUD»): до 127 байт, на экране до 8 сообщений.

Параметры

• x — позиция по горизонтали 0–1; -1 — по центру.
• y — позиция по вертикали 0–1; -1 — по центру.
• color — цвет (r, g, b).
• effect — 0 — появление, 1 — мерцание, 2 — печать по буквам.
• fade_in — секунд появления.
• fade_out — секунд исчезновения.
• hold — секунд на экране.
• fx_time — время эффекта 2 на букву.

Пример

banner = DirectorHud(y=0.3, color=(255, 140, 0), hold=5)
banner.show_all("Бомба заложена!")

Message

Message(kind: str | int, *, to: Player | None = None, reliable: bool = True)

User-сообщение клиенту по имени ("ScreenFade") или служебное по номеру.

Сообщение собирается целиком и уходит одним вызовом send (или при выходе из with) — незакрытого message_begin не бывает.

Параметры

• kind — имя user-сообщения или номер SVC_*.
• to — игрок; None — всем.
• reliable — гарантированная доставка (MSG_ONE/MSG_ALL).

Пример

with Message("ScreenFade", to=player) as m:
    m.short(4096).short(4096).short(0)
    m.byte(255).byte(0).byte(0).byte(100)

byte

byte(value: int) -> Message

WRITE_BYTE: 0–255.

char

char(value: int) -> Message

WRITE_CHAR: −128–127.

short

short(value: int) -> Message

WRITE_SHORT: −32768–32767.

long

long(value: int) -> Message

WRITE_LONG: 32-битное целое.

angle

angle(value: float) -> Message

WRITE_ANGLE: угол в градусах.

coord

coord(value: float) -> Message

WRITE_COORD: координата.

string

string(value: str) -> Message

WRITE_STRING: строка UTF-8.

entity

entity(value: int) -> Message

WRITE_ENTITY: индекс сущности.

send

send() -> None

Отправить сообщение.

Исключения

• LookupError — такого user-сообщения у мода нет.
• StaleHandleError — адресат вышел.