Agency-ProgressBar: Деталь интерфейса, которая тихо улучшает каждый скрипт

Маленький скрипт, огромное влияние

Прогресс-бары встречаются повсюду в FiveM: взлом замков, ремонт, отмывание денег, добыча, медицинская помощь. Стандартные реализации функциональны, но плоски. Agency-ProgressBar , наш взгляд на то, каким должен быть этот инструмент, когда разработчики заботятся о деталях.

Анатомия хорошей полосы прогресса

Хороший прогресс-бар одновременно сообщает четыре вещи: какое действие происходит, насколько оно продвинулось, сколько времени осталось и можно ли отменить. Большинство реализаций показывают только первые два. Agency-ProgressBar отображает все четыре с тонкими анимациями, делающими прогресс плавным, а не прерывистым.

Отмена, которая работает

Отмена, инициированная игроком, запускает короткую анимацию затухания, которая возвращает непрозрачность панели к нулю за 300 мс. Без резких исчезновений. Разработчики могут зарегистрировать обратный вызов отмены, чтобы скрипты корректно очищались, когда игроки прерывают действие.

Контекстное позиционирование

Полоса появляется рядом с соответствующим элементом на экране, над вашей головой для действий, направленных на себя, над целевым NPC для интерактивных действий. Больше не нужно читать статус действия внизу экрана, когда что-то происходит вверху. Такое контекстное позиционирование , тонкое улучшение UX, которое игроки ощущают, но не могут назвать.

Паттерн экспорта

Как и все наши утилитарные скрипты, Agency-ProgressBar предоставляет простой API экспорта: exports['agency-progressbar']:Play({label, duration, canCancel, onCancel, onDone}). Вставьте его в любой скрипт за считанные минуты. Он совместим с Agency-Notify, Agency-Hud и остальной частью нашей экосистемы без какой-либо специальной настройки.

Установка & настройка

Agency-ProgressBar is a drop-in utility with zero database dependency. Download from Tebex, drop the folder into your resources directory, add ensure agency-progressbar в server.cfg. Вот и всё. Ресурс начинает работать сразу, и любой скрипт может вызвать exports API при следующем перезапуске.

Если вы заменяете существующую панель прогресса (ox_lib progressBar, qb-progressbar и т.п.), поиск и замена имени вызова экспорта решают миграцию за несколько минут. Структура параметров специально близка к распространённым паттернам сообщества.

Параметры конфигурации

Открыто config.lua для настройки значений по умолчанию:

• Позиция по умолчанию , над головой игрока (по умолчанию) или фиксировано внизу по центру.
• Color scheme , градиент заливки. Поддерживает одноцветный, двухцветный градиент или отображение по степени серьёзности (зелёный для нормального, оранжевый для медленного, красный для критического).
• Отменить клавишу , какая клавиша отменяет отменяемую индикаторную шкалу прогресса. По умолчанию: backspace.
• Отменить анимацию , исчезновение с затемнением (по умолчанию), выезд или мгновенное исчезновение.
• Отображение времени , показывать оставшиеся секунды (по умолчанию), процент или ничего.
• Минимальная продолжительность , действия короче этого порога полностью пропускают индикатор выполнения. По умолчанию: 500 мс.

Совместимость с фреймворками

Agency-ProgressBar is fully standalone with no framework dependencies. It functions identically on QBCore, ESX, and custom server setups. The exports API is the only integration surface, no shared globals, no framework events, no permission checks. Install it and call it from any script regardless of origin.

Почему это важно для ролевой игры

Прогресс-бары , это примитив UX, который появляется во множестве игровых моментов: взлом замков, наручники, крафт, лечение, сбор улик, взлом. Когда эти бары выглядят несогласованно или ведут себя непоследовательно в разных скриптах, это создает тонкий визуальный шум, подрывающий целостность сервера.

Когда на вашем сервере все прогресс-бары используют Agency-ProgressBar, визуальный язык становится единым. Игроки интуитивно понимают, что означает полоса и как она ведёт себя. Поведение при отмене одинаково. Типографика соответствует остальному UI. Мелочи, но они складываются в заметно более отточенный опыт для игроков.

Контекстное позиционирование важнее, чем кажется. Прогресс-бар, закреплённый над головой вашего персонажа во время взлома замка, удерживает внимание на действии, а не в углу экрана. В напряжённые моменты, например, когда вас преследуют во время взлома, это помогает игрокам сохранять пространственную осведомлённость, пока бар виден.

Часто задаваемые вопросы

Могу ли я запускать несколько прогресс-баров одновременно?

Да. Каждый Play() вызов возвращает ID и управляет своим состоянием. Несколько полос располагаются вертикально над игроком с разумным интервалом. Это полезно для многоэтапных действий, где прогресс по параллельным задачам должен быть виден одновременно, хотя в большинстве RP-сценариев используется одна полоса за раз.

Как прикрепить progress bar к объекту или NPC вместо игрока?

Пройти target = {type = 'entity', id = entityNetId} поле в таблице опций. Полоса висит над указанным объектом, а не над игроком. Используйте это для действий по ремонту, медицинских действий на поверженных игроках или в любом случае, когда фокус действия внешней.

Можно ли с сервера принудительно сделать бар неотменяемым?

Да. Установите canCancel = false при вызове Play(). Клавиша отмены не действует, а анимация отмены не воспроизводится. Это уместно для действий, принудительно выполняемых сервером (анимации ареста, скриптовые катсцены), где прерывание игроком нарушило бы ход событий.

Работает ли это с анимациями ox_lib?

Да. Agency-ProgressBar не зависит от анимаций, вы управляете анимациями в своём скрипте вместе с вызовом прогресс-бара. Бар , это чисто UI-элемент. Используйте с любой библиотекой анимаций или вызовами анимаций FiveM отдельно.

Требования

• Сервер FiveM (любой фреймворк или standalone)
• аккаунт cfx.re с действующей лицензией Agency-ProgressBar
• Нет зависимости от базы данных
• Нет внешних зависимостей ресурсов

Практические примеры интеграции

Вот распространённые схемы интеграции Agency-ProgressBar с существующими скриптами:

Взлом замков: Звонок Play({label = 'Picking lock...', duration = 8000, canCancel = true, onCancel = cleanupFunction}) в начале попытки взлома замка. Используйте вместе с мини-игрой взлома, работающей параллельно. Если мини-игра провалилась, вызовите Dismiss() с возвращённым ID. Если успешна, дайте полосе завершиться естественно.

Медицинское лечение: Использовать target = {type = 'entity', id = patientNetId} чтобы закрепить панель над пациентом, а не над медиком. Игроки, наблюдающие сцену, видят прогресс лечения в точке оказания помощи, а не плавающим над головой медика.

Сбор доказательств: Установить canCancel = false для скриптового сбора улик, который нельзя прерывать (чтобы предотвратить отмену игроками и избежать оставления отпечатков пальцев на месте происшествия). Неотменяемая шкала сообщает игроку, что это действие обязательно, а не опционально.

Действия на стороне сервера: Отобразите индикатор прогресса на клиенте, пока серверное действие выполняется асинхронно. Когда серверный callback возвращается, либо дайте индикатору завершиться, либо закройте его раньше в зависимости от результата на сервере. Визуальная длительность должна примерно соответствовать ожидаемому времени обработки на сервере.