This translation is community contributed and may not be up to date. We only maintain the English version of the documentation. Read this manual in English
Defold поддерживает сборку игр для платформы HTML5 через обычное меню бандлинга, как и для других платформ. Кроме того, итоговая игра встраивается в обычную HTML-страницу, которую можно стилизовать через простую систему шаблонов.
Файл game.project содержит специфичные для HTML5 настройки:

Поддержка HTML5 в Defold работает на базе Emscripten (см. http://en.wikipedia.org/wiki/Emscripten). Вкратце: он создает изолированную область памяти для heap, в которой работает приложение. По умолчанию движок выделяет достаточно большой объем памяти (256 МБ). Этого более чем достаточно для типичной игры. В рамках оптимизации вы можете захотеть использовать меньшее значение. Для этого:
Для тестирования HTML5-сборке нужен HTTP-сервер. Defold создает его за вас, если выбрать Project ▸ Build HTML5.

Если вы хотите протестировать свой бандл, просто загрузите его на удаленный HTTP-сервер или создайте локальный сервер, например, с помощью Python в папке бандла. Python 2:
python -m SimpleHTTPServer
Python 3:
python -m http.server
или
python3 -m http.server
Нельзя тестировать HTML5-бандл, просто открыв файл index.html в браузере. Для этого нужен HTTP-сервер.
Если в консоли появляется ошибка "wasm streaming compile failed: TypeError: Failed to execute ‘compile’ on ‘WebAssembly’: Incorrect response MIME type. Expected ‘application/wasm’.", нужно убедиться, что ваш сервер использует MIME-тип application/wasm для файлов .wasm.
Создание HTML5-контента в Defold устроено просто и следует той же схеме, что и для других поддерживаемых платформ: выберите в меню Project ▸ Bundle... ▸ HTML5 Application...:

HTML5-бандлы поддерживают две архитектуры WebAssembly:
wasm-web — обычный однопоточный движок WebAssembly.wasm_pthread-web — движок WebAssembly, способный использовать потоки.Можно включить одну из архитектур или обе. Если включены обе, загрузчик выбирает wasm_pthread-web, когда браузер и среда хостинга её поддерживают, и в противном случае переходит на wasm-web. Канонические имена целей приведены в руководстве по Bob.
Многопоточному движку требуется SharedArrayBuffer на защищённой странице с изоляцией между источниками. Размещайте бандл по HTTPS (или на localhost) и настройте на сервере совместимые заголовки изоляции между источниками, обычно:
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp
Ресурсы из других источников, загружаемые страницей, также должны использовать совместимые заголовки CORS или Cross-Origin-Resource-Policy. Бандл, содержащий только wasm_pthread-web, не запустится, если эти требования не выполнены; включите wasm-web как резервный вариант, если игра может размещаться на сайте без поддержки изоляции между источниками.
HTML5-бандлам Defold требуется современный браузер с поддержкой WebAssembly. Internet Explorer 11 не поддерживается.
Когда вы нажмете Create bundle, появится запрос на выбор папки, в которой будет создано приложение. После завершения экспорта в ней будут находиться все файлы, необходимые для запуска приложения.
Выберите запрашиваемый графический контекст с помощью graphics.webgl_version_hint. По умолчанию используется WebGL 2; запросите WebGL 1, чтобы тестировать или использовать этот контекст в браузерах, поддерживающих обе версии.
Начиная с Defold 1.14.1, шейдеры WebGL 1 по умолчанию исключены. Отключите Exclude GLES 2.0, чтобы включить их, независимо от того, запрашиваете ли WebGL 1 напрямую или допускаете переход с WebGL 2. Чтобы явно запросить WebGL 1, задайте оба параметра в game.project:
[graphics]
webgl_version_hint = 1
[shader]
exclude_gles_sm100 = 0
html5.min_pixel_ratio и html5.max_pixel_ratio определяют, сколько пикселей рендеринга canvas используется на один CSS-пиксель. Размер canvas в CSS определяет размер игры на странице, а разрешение рендеринга — число пикселей, которые рисует движок.
Для использования ограничений включите High Dpi в разделе Display файла game.project. Тогда коэффициент плотности пикселей устройства в браузере ограничивается включёнными границами. По умолчанию оба ограничения равны 0, что отключает соответствующую границу. Значения должны быть конечными и неотрицательными; если оба положительны, минимум не должен превышать максимум.
Например, ограничьте коэффициент значением 1.5, чтобы снизить разрешение рендеринга на дисплеях с высокой плотностью пикселей:
[display]
high_dpi = 1
[html5]
min_pixel_ratio = 0
max_pixel_ratio = 1.5
В браузере с коэффициентом плотности пикселей устройства 3 canvas размером 800 × 600 CSS-пикселей при этой конфигурации будет отрисовываться в 1200 × 900 пикселей. Его отображаемый размер не меняется. В браузере с коэффициентом 1 тот же canvas по-прежнему отрисовывается в 800 × 600 пикселей, поскольку максимум не увеличивает коэффициент.
Поддерживаются и дробные коэффициенты меньше 1: например, максимум 0.75 даёт меньше пикселей рендеринга, чем размер отображения в CSS. Минимум выше коэффициента плотности пикселей браузера повышает разрешение рендеринга для суперсэмплинга. Ограничения применяются ко всем четырём вариантам Scale Mode, сохраняя их компоновку в CSS.
При отключённом High Dpi коэффициент остаётся 1 независимо от ограничений. В HTML5 window.get_display_scale() возвращает фактический коэффициент рендеринга после применения High DPI и ограничений.
По умолчанию загрузчик HTML5 проверяет размеры загруженных файлов движка и архива. При неудачной проверке загрузка повторяется, прежде чем загрузчик сообщит об ошибке:
html5.retry_count.Параметр html5.retry_time задаёт задержку между повторными попытками в обоих случаях.
Если ваш сервер, прокси или CDN намеренно изменяет отдаваемые файлы и их размеры, отключите проверку размера в game.project:
[html5]
verify_downloaded_file_size = 0
Отключение Verify Downloaded File Size не отключает проверку SHA-1, если она включена в бандл. См. настройки проекта для HTML5.
Engine Arguments файла game.project значение --verify-graphics-calls=false.Когда вы генерируете HTML5-версию игры, Defold предоставляет веб-страницу по умолчанию. Она ссылается на ресурсы стилей и скриптов, которые определяют, как именно будет отображаться ваша игра.
Каждый раз при экспорте приложения это содержимое создается заново. Если вы хотите изменить любой из этих элементов, необходимо внести изменения в настройки проекта. Для этого откройте game.project в редакторе Defold и прокрутите до раздела html5:

Подробнее о каждой опции см. в руководстве по настройкам проекта.
Вы не можете изменять файлы стандартного HTML/CSS-шаблона в папке builtins. Чтобы применить свои изменения, скопируйте нужный файл из builtins и укажите этот файл в game.project.
Canvas не должен быть оформлен с помощью border или padding. Если сделать это, координаты ввода мыши будут неверными.
В game.project можно отключить кнопку Fullscreen и ссылку Made with Defold.
Defold предоставляет темную и светлую тему для index.html. По умолчанию установлена светлая тема, но ее можно изменить, заменив файл Custom CSS. Также в поле Scale Mode доступны четыре предустановленных режима масштабирования.
При включённом High Dpi в разделе Display файла game.project все режимы масштабирования используют фактический коэффициент плотности пикселей, включая его ограничения, для определения размера буфера рендеринга canvas.
В режиме Fit размер canvas будет изменен так, чтобы на экране целиком отображался игровой canvas с сохранением исходных пропорций. В Downscale Fit отличие только в том, что размер меняется лишь тогда, когда внутренняя область веб-страницы меньше исходного игрового canvas, но не увеличивается, если страница больше исходного canvas игры.

В режиме Stretch размер canvas будет изменен так, чтобы полностью заполнить внутреннюю область веб-страницы.

В режиме No Scale ширина и высота canvas в CSS соответствуют Width и Height из раздела Display файла game.project. Разрешение рендеринга по-прежнему использует фактический коэффициент плотности пикселей.

Мы используем язык шаблонов Mustache для создания файла index.html. Во время сборки или бандлинга HTML- и CSS-файлы проходят через компилятор, который умеет заменять определенные токены значениями, зависящими от настроек проекта. Эти токены всегда заключены в двойные или тройные фигурные скобки ({{TOKEN}} или {{{TOKEN}}}) в зависимости от того, нужно ли экранировать последовательности символов. Эта возможность может быть полезна, если вы часто меняете настройки проекта или планируете переиспользовать материалы в других проектах.
Подробнее о языке шаблонов Mustache можно прочитать в руководстве.
Любое значение из game.project может быть токеном. Например, если вы хотите использовать значение Width из раздела Display:

Откройте game.project как текст и посмотрите на [section_name] и имя нужного поля. Затем можно использовать токен вида {{section_name.field}} или {{{section_name.field}}}.

Например, в HTML-шаблоне внутри JavaScript:
function doSomething() {
var x = {{display.width}};
// ...
}
Также доступны следующие пользовательские токены:
false, если html5.splash_image в game.project пуст.{{#DEFOLD_SPLASH_IMAGE}}
background-image: url("{{DEFOLD_SPLASH_IMAGE}}");
{{/DEFOLD_SPLASH_IMAGE}}
html5.archive_location_prefix.html5.archive_location_suffix.true, если префикс архива задаёт источник HTTP или HTTPS, в том числе URL без указания протокола, например //cdn.example.com/archive. Равен false для относительных префиксов архива.true, если бандл включает движок WebAssembly: wasm-web или wasm_pthread-web.true, если бандл включает wasm_pthread-web. Используйте его, чтобы избежать предварительной загрузки неверного варианта движка, когда загрузчик выбирает архитектуру во время выполнения.<style>
{{{DEFOLD_CUSTOM_CSS_INLINE}}}
</style>
Важно, чтобы этот встроенный блок находился перед загрузкой основного скрипта приложения. Поскольку он включает HTML-теги, этот макрос должен использоваться в тройных фигурных скобках {{{TOKEN}}}, чтобы последовательности символов не экранировались.
true, если html5.scale_mode имеет значение Downscale Fit.true, если html5.scale_mode имеет значение Fit.true, если html5.scale_mode имеет значение No Scale.true, если html5.scale_mode имеет значение Stretch.html5.heap_size, преобразованный в байты.html5.engine_arguments, разделенные символом ,.При создании собственного шаблона параметры загрузчика движка можно изменить, присвоив значения глобальному объекту CUSTOM_PARAMETERS. Встроенный шаблон предоставляет для таких настроек намеренно пустой блок <script id="engine-setup">.
Блок engine-setup должен находиться после скрипта, загружающего dmloader.js, но перед блоком engine-start, который вызывает EngineLoader.load().
Например:
<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-сборки поддерживают файловые операции, такие как sys.save(), sys.load() и io.open(), но внутренне они работают иначе, чем на других платформах. Когда JavaScript выполняется в браузере, понятия реальной файловой системы не существует, а локальный доступ к файлам блокируется из соображений безопасности. Вместо этого Emscripten (а значит и Defold) использует IndexedDB — встроенную в браузер базу данных для постоянного хранения данных — чтобы создать виртуальную файловую систему в браузере. Важное отличие от файловых операций на других платформах в том, что между записью в файл и фактическим сохранением данных в базе может быть небольшая задержка. Обычно содержимое IndexedDB можно посмотреть через консоль разработчика браузера.
Иногда нужно передать игре дополнительные аргументы до запуска или в момент запуска. Это может быть, например, id пользователя, session token или указание, какой уровень загружать при старте. Сделать это можно несколькими способами, некоторые из которых описаны ниже.
Можно указать дополнительные аргументы при настройке и загрузке движка. Во время выполнения их можно получить через 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
Вы можете передавать аргументы как часть query-параметров в URL страницы и считывать их во время выполнения:
https://www.mygame.com/index.html?foo1=bar1&foo2=bar2
local url = html5.run("window.location")
print(url)
Полная вспомогательная функция, которая получает все query-параметры в виде Lua-таблицы:
local function get_query_parameters()
local url = html5.run("window.location")
-- получить строку запроса из URL (часть после ?)
local query = url:match(".*?(.*)")
if not query then
return {}
end
local params = {}
-- перебрать все пары ключ-значение
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-игры рекомендуется сосредоточиться на следующих областях:
A: В некоторых случаях невозможно запустить игру в браузере локально прямо из файловой системы. При запуске из редактора игра раздаётся через локальный web server. Например, можно использовать SimpleHTTPServer в Python:
$ python -m SimpleHTTPServer [port]
A: Обычно это происходит, если вы используете Windows, делаете сборку и коммитите её в Git. Если в Git неправильно настроены окончания строк, он изменит line endings и, как следствие, размер данных. Чтобы решить проблему, следуйте этим инструкциям: https://docs.github.com/en/free-pro-team@latest/github/using-git/configuring-git-to-handle-line-endings