Розробка для HTML5

Defold підтримує збирання ігор для платформи HTML5 через звичайне меню пакування, як і для інших платформ. Крім того, отриману гру вбудовано у звичайну HTML-сторінку, оформлення якої можна змінювати за допомогою простої системи шаблонів.

Файл game.project містить налаштування для HTML5:

Розмір купи пам’яті

Підтримка HTML5 у Defold ґрунтується на Emscripten (див. http://en.wikipedia.org/wiki/Emscripten). Якщо коротко, він створює ізольовану область пам’яті для купи (heap), у якій працює застосунок. За замовчуванням рушій виділяє значний обсяг пам’яті (256 МБ). Для типової гри цього має бути більш ніж достатньо. Під час оптимізації ви можете вибрати менше значення. Для цього виконайте такі кроки:

1. Установіть бажане значення heap_size. Воно має бути виражене в мегабайтах.
2. Створіть пакет HTML5 (див. нижче)

Тестування збірки HTML5

Для тестування збірки HTML5 потрібен HTTP-сервер. Defold створює його, якщо вибрати Project ▸ Build HTML5.

Щоб протестувати пакет, завантажте його на віддалений HTTP-сервер або створіть локальний сервер, наприклад за допомогою Python у папці пакета. Python 2:

python -m SimpleHTTPServer

Python 3:

python -m http.server

або

python3 -m http.server

Створення пакета HTML5

Створювати вміст HTML5 за допомогою Defold просто: процес такий самий, як і для всіх інших підтримуваних платформ. Виберіть у меню Project ▸ Bundle... ▸ HTML5 Application...:

Пакети HTML5 підтримують дві архітектури WebAssembly:

• wasm-web — звичайний рушій WebAssembly без підтримки потоків.
• wasm_pthread-web — рушій WebAssembly, який може використовувати потоки.

Можна включити будь-яку з цих архітектур або обидві. Якщо включено обидві, завантажувач вибирає wasm_pthread-web, коли браузер і середовище розміщення підтримують її, а в іншому разі використовує wasm-web. Канонічні назви цільових платформ наведено в посібнику з Bob.

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

Пакети Defold HTML5 потребують сучасного браузера з підтримкою WebAssembly. Internet Explorer 11 не підтримується.

Після натискання кнопки Create bundle вам буде запропоновано вибрати папку, у якій потрібно створити застосунок. Після завершення експорту ви знайдете в ній усі файли, необхідні для запуску застосунку.

Відомі проблеми й обмеження

• Гаряче перезавантаження (Hot Reload) — гаряче перезавантаження не працює у збірках HTML5. Для отримання оновлень із редактора застосунки Defold мають запускати власний мініатюрний вебсервер, що неможливо у збірці HTML5.
• Chrome
  • Повільні налагоджувальні збірки — у налагоджувальних збірках для HTML5 ми перевіряємо всі графічні виклики WebGL, щоб виявляти помилки. На жаль, під час тестування в Chrome це працює дуже повільно. Перевірку можна вимкнути, установивши в полі Engine Arguments файлу game.project значення --verify-graphics-calls=false.
• Підтримка геймпадів — зверніться до документації про геймпади, щоб дізнатися про особливості й кроки, які можуть знадобитися для HTML5.

Налаштування пакета HTML5

Під час створення HTML5-версії гри Defold надає стандартну вебсторінку. Вона посилається на ресурси стилів і скриптів, які визначають вигляд вашої гри.

Щоразу під час експорту застосунку цей вміст створюється заново. Щоб налаштувати будь-який із цих елементів, потрібно змінити налаштування проєкту. Для цього відкрийте game.project у редакторі Defold і прокрутіть до розділу html5:

Докладнішу інформацію про кожен параметр наведено в посібнику з налаштувань проєкту.

У game.project можна вимкнути кнопку Fullscreen і посилання Made with Defold. Defold надає темну й світлу теми для index.html. За замовчуванням установлено світлу тему, але її можна змінити, змінивши файл Custom CSS. Також у полі Scale Mode можна вибрати один із чотирьох попередньо визначених режимів масштабування.

Downscale Fit і Fit

У режимі Fit розмір полотна змінюється так, щоб усе ігрове полотно вміщувалося на екрані зі збереженням початкових пропорцій. Єдина відмінність режиму Downscale Fit полягає в тому, що розмір змінюється лише тоді, коли внутрішній розмір вебсторінки менший за початкове полотно гри, але не збільшується, коли вебсторінка більша за нього.

Stretch

У режимі Stretch розмір полотна змінюється так, щоб воно повністю заповнювало внутрішній простір вебсторінки.

No Scale

У режимі No Scale розмір полотна точно відповідає значенню, заданому у файлі game.project, у розділі [display].

Токени

Для створення файлу index.html ми використовуємо мову шаблонів Mustache. Під час збирання або пакування файли HTML і CSS проходять через компілятор, який може замінювати певні токени значеннями, що залежать від налаштувань проєкту. Ці токени завжди взято у подвійні або потрійні фігурні дужки ({{TOKEN}} або {{{TOKEN}}}), залежно від того, чи потрібно екранувати послідовності символів. Ця можливість корисна, якщо ви часто змінюєте налаштування проєкту або плануєте повторно використовувати матеріал в інших проєктах.

Будь-який параметр game.project може бути токеном. Наприклад, якщо ви хочете використати значення Width із розділу Display:

Відкрийте game.project як текст і перевірте [section_name] та назву поля, яке хочете використати. Потім його можна використати як токен: {{section_name.field}} або {{{section_name.field}}}.

Наприклад, у JavaScript в HTML-шаблоні:

function doSomething() {
    var x = {{display.width}};
    // ...
}

Також доступні такі спеціальні токени:

DEFOLD_SPLASH_IMAGE

Записує ім’я файлу зображення заставки або false, якщо html5.splash_image у game.project порожнє

{{#DEFOLD_SPLASH_IMAGE}}
		background-image: url("{{DEFOLD_SPLASH_IMAGE}}");
{{/DEFOLD_SPLASH_IMAGE}}

exe-name

Назва проєкту без неприпустимих символів

DEFOLD_CUSTOM_CSS_INLINE

Місце, куди вбудовується вміст CSS-файлу, зазначеного в налаштуваннях game.project.

<style>
{{{DEFOLD_CUSTOM_CSS_INLINE}}}
</style>

DEFOLD_SCALE_MODE_IS_DOWNSCALE_FIT

Цей токен має значення true, якщо html5.scale_mode дорівнює Downscale Fit.

DEFOLD_SCALE_MODE_IS_FIT

Цей токен має значення true, якщо html5.scale_mode дорівнює Fit.

DEFOLD_SCALE_MODE_IS_NO_SCALE

Цей токен має значення true, якщо html5.scale_mode дорівнює No Scale.

DEFOLD_SCALE_MODE_IS_STRETCH

Цей токен має значення true, якщо html5.scale_mode дорівнює Stretch.

DEFOLD_HEAP_SIZE

Розмір купи пам’яті, зазначений у html5.heap_size файлу game.project, перетворений у байти.

DEFOLD_ENGINE_ARGUMENTS

Аргументи рушія, зазначені в html5.engine_arguments файлу game.project і розділені символом ,.

build-timestamp

Часова мітка поточного збирання в секундах.

Додаткові параметри

Якщо ви створюєте власний шаблон, можна змінювати параметри завантажувача рушія, призначаючи значення в глобальному об’єкті CUSTOM_PARAMETERS. Вбудований шаблон містить навмисно порожній блок <script id="engine-setup"> для цих налаштувань.

Наприклад:

    <script id="engine-setup" type="text/javascript">
        CUSTOM_PARAMETERS.disable_context_menu = false;
        CUSTOM_PARAMETERS.unsupported_webgl_callback = function() {
            console.log("Oh-oh. WebGL not supported...");
        };
    </script>

CUSTOM_PARAMETERS може містити, зокрема, такі поля:

'archive_location_filter':
    Filter function that will run for each archive path.

'unsupported_webgl_callback':
    Function that is called if WebGL is not supported.

'engine_arguments':
    List of arguments (strings) that will be passed to the engine.

'custom_heap_size':
    Number of bytes specifying the memory heap size.

'disable_context_menu':
    Disables the right-click context menu on the canvas element if true.

'retry_time':
    Pause in seconds before retry file loading after error.

'retry_count':
    How many attempts we do when trying to download a file.

'can_not_download_file_callback':
    Function that is called if you can't download file after 'retry_count' attempts.

'resize_window_callback':
    Function that is called when resize/orientationchanges/focus events happened

'start_success':
    Function that is called just before main is called upon successful load.

'update_progress':
    Function that is called as progress is updated. Parameter progress is updated 0-100.

Файлові операції в HTML5

Збірки HTML5 підтримують файлові операції, як-от sys.save(), sys.load() та io.open(), але внутрішня обробка цих операцій відрізняється від інших платформ. Під час виконання JavaScript у браузері немає повноцінного поняття файлової системи, а доступ до локальних файлів заблоковано з міркувань безпеки. Натомість Emscripten (а отже, і Defold) використовує IndexedDB, базу даних у браузері для постійного зберігання даних, щоб створити віртуальну файлову систему в браузері. Важлива відмінність від доступу до файлової системи на інших платформах полягає в тому, що між записом у файл і фактичним збереженням зміни в базі даних може бути невелика затримка. Консоль розробника браузера зазвичай дає змогу переглядати вміст IndexedDB.

Передавання аргументів у гру HTML5

Іноді потрібно передати грі додаткові аргументи до запуску або під час нього. Це може бути, наприклад, ідентифікатор користувача, токен сеансу або рівень, який потрібно завантажити під час запуску гри. Це можна зробити кількома різними способами, деякі з яких описано тут.

Аргументи рушія

Під час налаштування й завантаження рушія можна вказати додаткові аргументи рушія. Їх можна отримати під час виконання за допомогою sys.get_config_string(). Призначте аргументи безпосередньо в CUSTOM_PARAMETERS.engine_arguments у блоці engine-setup файлу index.html:

    <script id="engine-setup" type="text/javascript">
        CUSTOM_PARAMETERS.engine_arguments = [
            "--config=example.foo1=bar1",
            "--config=example.foo2=bar2"
        ];
    </script>

Призначення нового масиву замінює всі аргументи рушія, налаштовані в game.project. Щоб зберегти ці аргументи й додати ще один, натомість використовуйте CUSTOM_PARAMETERS.engine_arguments.push("--config=example.foo3=bar3").

Також можна додати --config=example.foo1=bar1, --config=example.foo2=bar2 у поле Engine Arguments розділу HTML5 у game.project. Значення, розділені комами, додаються до CUSTOM_PARAMETERS.engine_arguments у згенерованому файлі dmloader.js.

Під час виконання значення можна отримати так:

local foo1 = sys.get_config_string("example.foo1")
local foo2 = sys.get_config_string("example.foo2")
print(foo1) -- bar1
print(foo2) -- bar2

Аргументи запиту в URL

Ви можете передавати аргументи як параметри запиту в URL сторінки й читати їх під час виконання:

https://www.mygame.com/index.html?foo1=bar1&foo2=bar2

local url = html5.run("window.location")
print(url)

Повна допоміжна функція для отримання всіх параметрів запиту у вигляді таблиці Lua:

local function get_query_parameters()
    local url = html5.run("window.location")
    -- get the query part of the url (the bit after ?)
    local query = url:match(".*?(.*)")
    if not query then
        return {}
    end

    local params = {}
    -- iterate over all key value pairs
    for kvp in query:gmatch("([^&]+)") do
        local key, value = kvp:match("(.+)=(.+)")
        params[key] = value
    end
    return params
end

function init(self)
    local params = get_query_parameters()
    print(params.foo1) -- bar1
end

Оптимізація

Ігри HTML5 зазвичай мають суворі вимоги до початкового обсягу завантаження, часу запуску й використання пам’яті, щоб вони швидко завантажувалися та добре працювали на малопотужних пристроях і за повільного інтернет-з’єднання. Щоб оптимізувати гру HTML5, рекомендовано зосередитися на таких напрямах:

• Використання пам’яті
• Розмір рушія
• Розмір гри

Поширені запитання

П: Чому мій застосунок HTML5 зависає на заставці в Chrome?

В: У деяких випадках гру неможливо запустити в браузері безпосередньо з локальної файлової системи. Під час запуску з редактора гра обслуговується локальним вебсервером. Ви можете, наприклад, скористатися SimpleHTTPServer у Python:

$ python -m SimpleHTTPServer [port]

П: Чому моя гра аварійно завершується з помилкою “Unexpected data size” під час завантаження?

В: Зазвичай це трапляється, коли ви створюєте збірку у Windows і додаєте її до Git. Якщо завершення рядків у Git налаштовано неправильно, Git змінюватиме їх, а отже, і розмір даних. Щоб розв’язати проблему, дотримуйтеся цих інструкцій: https://docs.github.com/en/free-pro-team@latest/github/using-git/configuring-git-to-handle-line-endings