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 , готовый к установке инструмент, которому не нужна база данных. Скачайте его с Tebex, поместите папку в каталог ресурсов и добавьте ensure agency-progressbar в server.cfg. Вот и всё. Ресурс начинает работать сразу, и любой скрипт может вызвать exports API при следующем перезапуске.

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

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

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

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

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

Agency-ProgressBar полностью автономен и не зависит от фреймворков. Он одинаково работает на QBCore, ESX и пользовательских настройках сервера. Для интеграции используется только API exports: никаких общих глобальных переменных, событий фреймворка и проверок прав. Установите его и вызывайте из любого скрипта, независимо от его происхождения.

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

Прогресс-бары , это примитив 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 возвращается, либо дайте индикатору завершиться, либо закройте его раньше в зависимости от результата на сервере. Визуальная длительность должна примерно соответствовать ожидаемому времени обработки на сервере.