Extended HUD Informer

Плагин для AMX Mod X, выводящий игрокам HUD-информеры — персистентные hud-сообщения, которые постоянно висят на экране и обновляются с заданной частотой. По умолчанию используется классический HUD, но при желании вывод можно переключить на director HUD (dhud) через флаг DHUD (см. «HUD sync и dHUD»).

Текст информера, частота обновления, цвет и расположение полностью настраиваются в JSON-конфиге. В тексте поддерживаются плейсхолдеры из ParamsController — как глобальные, так и игровые (полный список — в документации ParamsController).

Плагин использует встроенные плейсхолдеры ParamsController@1.5.0 и полностью пригоден для использования на реальных серверах.

Возможности

• Несколько информеров в одном конфиге (объект или массив объектов на файл, несколько файлов, вложенные папки).
• Настройка текста (с плейсхолдерами), цвета, позиции (X/Y), частоты обновления, времени удержания/появления/исчезания и HUD-канала. При необходимости вывод переключается на director HUD (dhud) через флаг DHUD.
• Встроенные плейсхолдеры ParamsController — глобальные и игровые «колбечные» — всегда актуальны в момент обновления HUD.
• Скомпилированные шаблоны (PCPH_CompileTemplate) — текст разбирается один раз, обновление HUD максимально дёшево.
• Публичный API для других плагинов: поиск, включение/выключение, принудительный показ информера.

Требования

• AMX Mod X 1.10.x.
• ParamsController 1.5.0 или новее.
• Модули cstrike / fun не требуются — плагин игро-независимый.

Установка

1. Соберите плагин (см. ниже) или возьмите готовый .amxx из релиза.
2. Скопируйте:
   • ExtendedHudInformer.amxx → addons/amxmodx/plugins/;
   • содержимое configs/plugins/ExtendedHudInformer/ → addons/amxmodx/configs/plugins/ExtendedHudInformer/.
3. Добавьте в addons/amxmodx/configs/plugins.ini:

   params_controller.amxx
   extendedhudinformer.amxx
   

   ParamsController обязательно должен быть загружен (плагин использует его natives). Порядок не критичен, но оба должны быть в списке.
4. Перезапустите сервер или выполните amxx reload extendedhudinformer.amxx.

Сборка

Проект собирается через amxx-builder:

amxb build

Манифест amxbuild.yml сам подтянет ParamsController@1.5.0 как зависимость.

Конфигурация

Конфиги лежат в папке addons/amxmodx/configs/plugins/ExtendedHudInformer/. Плагин рекурсивно обходит её и загружает все файлы с расширением .json. Файлы и папки, начинающиеся с ! или ., пропускаются (например, !disabled.json).

Каждый файл может содержать один объект информера или массив объектов:

[
    { ...информер 1... },
    { ...информер 2... }
]

Поля информера

Поле	Тип	Обязательно	По умолчанию	Описание
Key	строка	—	авто	Уникальный ключ информера (до 64 символов). Используется в API и логах. Если не задан (или пустой) — генерируется автоматически (#auto:N); это удобно, когда идентифицировать информер через API не нужно. Дубликаты явных ключей пропускаются с предупреждением.
Text	строка	✅	—	Текст информера с плейсхолдерами (до 512 символов). Многострочность — через \n. Компилируется в шаблон при загрузке.
Color	массив/объект/строка	—	[200, 100, 0]	Цвет текста. Форматы: [R, G, B], {"R":255,"G":255,"B":255} (или Red/Green/Blue), "255,255,255".
X	число	—	-1.0	Горизонтальная позиция в процентах экрана. -1.0 — по центру, 0.0 — слева, 1.0 — справа.
Y	число	—	0.35	Вертикальная позиция в процентах экрана. 0.0 — сверху, 1.0 — снизу.
UpdateTime	число	—	1.0	Частота обновления, секунды. <= 0 → 1.0, меньше 0.1 → кламп до 0.1 (движок не поддерживает быстрее) с предупреждением в лог.
HoldTime	число	—	авто	Сколько секунд сообщение удерживается на экране. 0 (или не задано) → UpdateTime + 0.5 (сообщение не мигает).
FadeInTime	число	—	0.0	Время плавного появления, секунды.
FadeOutTime	число	—	0.0	Время плавного исчезания, секунды.
Channel	целое	—	-1 (авто)	HUD-канал. Допустимо -1..4. Учитывается только при "Sync": false (при Sync и DHUD игнорируется). Для перманентных сообщений рекомендуется фиксированный канал 0-3 (см. «Советы»).
Sync	bool	—	true	Вывод через HUD-sync API (CreateHudSyncObj / ShowSyncHudMsg). Sync-объект сам очищает предыдущее сообщение перед записью нового, что убирает фликер. Пока Sync включён, поле Channel игнорируется (sync-объект ведёт свой канал сам).
DHUD	bool	—	false	Вывод как director HUD-сообщение (set_dhudmessage / show_dhudmessage) вместо классического HUD. Имеет приоритет над Sync. При true поля Channel и Sync игнорируются.
Enabled	bool	—	true	Включён ли информер. false — задача не запускается, информер можно включить через API.

Пример (ExampleInformers.json уже включён в поставку):

[
    {
        "Key": "welcome",
        "Text": "Welcome to {server-name}, {p:name}!\nMap: {map}\nPlayers: {players-count}/{max-players-count}\nTime: {time}",
        "Color": [0, 200, 100],
        "X": -1.0,
        "Y": 0.05,
        "UpdateTime": 1.0,
        "Sync": true,
        "DHUD": false
    },
    {
        "Key": "player-stats",
        "Text": "Health: {p:health} | Armor: {p:armor}\nFrags: {p:frags} | Ping: {p:ping}\nConnected: {p:connect-time}",
        "Color": [255, 200, 0],
        "X": 0.02,
        "Y": 0.15,
        "UpdateTime": 0.5,
        "Sync": false,
        "DHUD": false,
        "Channel": 2
    },
    {
        "Key": "server-info",
        "Text": "Server uptime: {uptime}\nNext map: {nextmap}",
        "Color": [200, 200, 200],
        "X": 0.02,
        "Y": 0.85,
        "UpdateTime": 5.0,
        "DHUD": true
    }
]

В примере показаны все три варианта вывода: welcome — HUD sync ("Sync": true, по умолчанию), player-stats — классический HUD по каналу ("Sync": false, учитывается "Channel"), server-info — director HUD ("DHUD": true). Поскольку DHUD имеет приоритет над Sync, значение Sync при "DHUD": true роли не играет — отдельный пример с "Sync": false не нужен.

HUD sync и dHUD

По умолчанию ("Sync": true) информер выводится через HUD-sync API (CreateHudSyncObj / ShowSyncHudMsg). Sync-объект перед записью нового сообщения сам очищает предыдущее, поэтому мигание не возникает и фиксированный Channel для этого не нужен: при включённом Sync поле Channel игнорируется.

"Sync": false возвращает классическое поведение через Channel. Теперь канал снова важен, и его нужно подбирать так, чтобы информеры не перебивали друг друга (см. «Советы»).

"DHUD": true переключает информер на director HUD (set_dhudmessage / show_dhudmessage). Флаг имеет приоритет над Sync, поэтому при DHUD игнорируются и Channel, и Sync. У dHUD есть ограничения движка:

• параметра канала у него нет вообще, так что Channel к нему неприменим;
• текст ограничен 128 символами, более длинный движок обрезает автоматически;
• сообщения стековые: одновременно на экране до 8 штук, более старые вытесняются, а очистить конкретное сообщение нельзя.

Из-за этого для персистентных информеров dHUD менее гибок, чем классический HUD.

Плейсхолдеры

Плейсхолдеры имеют вид {key} (глобальные) или {prefix:key} (групповые). Если плейсхолдер не зарегистрирован или группа неизвестна — он останется в тексте как есть.

Все плейсхолдеры предоставляются самим ParamsController — плагин своих не регистрирует. Полный список и описание плейсхолдеров смотрите в его документации.

Механизм

Игровые плейсхолдеры — реактивные: ParamsController запрашивает значение у колбека при каждом форматировании, поэтому они всегда актуальны без дополнительных событий. Перед форматированием HUD плагин кладёт в стек группы p контекст текущего игрока (PCPH_Group_PushIntContext), а после — снимает его (PCPH_Group_PopContext). Для обновления HUD используется скомпилированный шаблон (PCPH_CompileTemplate + PCPH_FormatTemplate) — строка с плейсхолдерами разбирается один раз при загрузке конфига, дальнейшее обновление не выполняет сканирование строки.

Советы

• HUD-каналы. При Sync (по умолчанию) канал задавать обычно не нужно: sync-объект сам очищает предыдущее сообщение, поэтому мигания нет. Фиксированный Channel (0-3) имеет смысл только когда Sync выключен — тогда каждому информеру нужен свой канал, иначе они будут «перебивать» друг друга. Канал 4 используется игрой (радар/служебные сообщения) — лучше его избегать.
• Многострочность. Используйте \n в Text. Не забывайте, что JSON требует экранирования — \n в файле конфига так и пишется как \n.
• Лимиты. Text ограничен 512 символами (это ограничение типа PH-Template). Сегменты текста длиннее 512 символов обрезаются самим ParamsController.
• HoldTime. Если сообщение мигает — увеличьте HoldTime так, чтобы оно было больше UpdateTime (по умолчанию это делается автоматически).
• Изменение конфига. После правки JSON выполните amxx reload extendedhudinformer.amxx — конфиг перечитается, все шаблоны перекомпилируются.
• Отключение информера без удаления. Поставьте "Enabled": false или переименуйте файл в !something.json.

API для разработчиков

Подключите <ExtendedHudInformer> в своём плагине. Перед использованием убедитесь, что библиотека загружена:

if (!LibraryExists("ExtendedHudInformer", LibType_Library)) {
    // плагин ExtendedHudInformer не загружен
}

native ExtendedHudInformer_Init();
// Принудительная инициализация (вызовется ParamsController_Init + загрузка конфигов).
// Идемпотентна.

native T_ExtendedHudInformer:ExtendedHudInformer_Find(const key[]);
// Поиск информера по Key. Invalid_ExtendedHudInformer (-1), если не найден.

native bool:ExtendedHudInformer_IsEnabled(const T_ExtendedHudInformer:informer);
// Включён ли информер (запущена ли его задача обновления).

native ExtendedHudInformer_SetEnabled(const T_ExtendedHudInformer:informer, const bool:enabled);
// Включить/выключить информер на лету.

native ExtendedHudInformer_Show(const T_ExtendedHudInformer:informer, const playerIndex = 0);
// Принудительно показать информер сейчас. playerIndex = 0 — всем игрокам.

Пример — выключить информер на время события:

new T_ExtendedHudInformer:informer = ExtendedHudInformer_Find("player-stats");
if (informer != Invalid_ExtendedHudInformer) {
    ExtendedHudInformer_SetEnabled(informer, false);
}

Отладка

• Все этапы инициализации и регистрации пишутся в лог сервера с префиксом [INFO].
• Ошибки конфига (неверный тип поля, дубликат Key, пустой Key и т.п.) пишутся в лог с префиксом [JSON][WARNING] и указанием файла — проблемный информер пропускается, остальные продолжают работать.
• Если папка конфигов не найдена или JSON-файл не парсится — плагин аварийно завершает загрузку (как и другие плагины экосистемы) с явным сообщением в консоли.
• Список зарегистрированных типов параметров: params_controller_types (srvcmd).
• Типичная проблема: плагин не загружается с ошибкой «Native not found». Причина — ParamsController не загружен или загружен после ExtendedHudInformer. Проверьте plugins.ini.