Пользовательский экран загрузки для FiveM: loadscreen, fxmanifest и shutdown

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

#Ресурс

Создайте папку с HTML и его активами:

resources/[ui]/my_loadscreen/
  fxmanifest.lua
  index.html
  css/style.css
  js/app.js
  img/background.jpg
  audio/music.ogg

#fxmanifest.lua

fx_version 'cerulean'
game 'gta5'

loadscreen 'index.html'

files {
    'index.html',
    'css/style.css',
    'js/app.js',
    'img/background.jpg',
    'audio/music.ogg',
}

Два момента имеют значение здесь:

• loadscreen 'index.html' называет страницу, которую показывает FiveM.
• Каждый файл, который использует страница, включая сам HTML, должен быть в files. Файл, который не указан, возвращает 404 и экран пуст или сломан в этой части. Паттерн типа 'img/*' разрешён для перечисления всей папки.

Добавьте её в server.cfg:

ensure my_loadscreen

#Минимальный index.html

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <link rel="stylesheet" href="css/style.css">
</head>
<body>
  <h1>Welcome to my server</h1>
  <div id="bar"><div id="fill"></div></div>
  <audio id="music" src="audio/music.ogg" autoplay loop></audio>
  <script src="js/app.js"></script>
</body>
</html>

Используйте относительные пути, как выше. Страница работает в браузере игры, поэтому вы можете использовать обычный HTML, CSS и JavaScript. Для полосы прогресса, страница получает сообщения при загрузке игры:

window.addEventListener('message', (e) => {
  if (e.data.eventName === 'loadProgress') {
    document.getElementById('fill').style.width = (e.data.loadFraction * 100) + '%'
  }
})

#Только один экран загрузки

FiveM показывает один экран загрузки. Если два ресурса объявляют loadscreen, используется только один, и какой один может меняться между запусками. Итак:

• Удалите или остановите любой другой ресурс экрана загрузки из server.cfg.
• Когда вы хотите протестировать новый, закомментируйте старую строку вместо запуска обоих.

#Закройте экран самостоятельно

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

loadscreen_manual_shutdown 'yes'

Затем клиентский скрипт должен закрыть его:

-- client.lua
CreateThread(function()
    -- wait until your own condition: player spawned, character chosen...
    while not NetworkIsPlayerActive(PlayerId()) do
        Wait(100)
    end

    ShutdownLoadingScreenNui()
end)

ShutdownLoadingScreenNui закрывает страницу NUI вашего экрана загрузки. Скрипт, который обрабатывает спавн, как скрипт мультихарактера, часто вызывает его, или native за ним, для вас. Проверьте этот скрипт сначала, затем добавьте свой собственный вызов только если ничего другого не делает.

Внимание: если вы установите loadscreen_manual_shutdown 'yes' и ничего не вызовет shutdown, игроки останутся на экране загрузки навсегда. Если это происходит, см. игроки застревают на экране загрузки.

#Музыка и видео: держите их лёгкими

Всё в files загружается каждым игроком. Тяжёлый экран загрузки делает ожидание дольше, что противоположно цели.

• Музыка: используйте .ogg или .mp3, несколько минут максимум, и умеренный битрейт. Трек на 3 MB хорош, трек на 60 MB — нет. Добавьте кнопку отключения звука, и установите громкость низко в коде, так как громкий старт раздражает игроков.
• Видео: короткое и зацикленное, в .webm или .mp4, маленькое разрешение и низкий битрейт. Лучше ещё, используйте хорошее фоновое изображение, которое намного меньше.
• Изображения: сжимайте их. Фон 200 на 400 KB выглядит так же, как 8 MB на большинстве экранов.
• Шрифты и библиотеки: положите их в ресурс. Загрузка их из интернета при присоединении делает страницу медленнее, и она не удаётся, если хост выключен.

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

#Опционально: курсор

Если вы хотите, чтобы игрок нажимал на экран загрузки, для правил или меню, добавьте следующее в манифест:

loadscreen_cursor 'yes'

#Распространённые проблемы

• Пустой экран, без стиля. Файл отсутствует в files, или путь в HTML неправильный.
• Показывается экран по умолчанию. Ресурс не запущен, или строка loadscreen отсутствует.
• Он никогда не закрывается. Вы установили loadscreen_manual_shutdown 'yes' и никакой скрипт не вызывает ShutdownLoadingScreenNui().
• Музыка не воспроизводится. Проверьте путь файла и формат. Сначала протестируйте страницу в обычном браузере.

#Контрольный список