Сборка Web: WASM и варианты шаблонов — документация

Emscripten, threads, dynamic linking, состав ZIP и локальная диагностика.

Выберите нужный результат

Эта инструкция собирает WebAssembly-шаблоны из исходников движка. Экспорт вашей игры — отдельный шаг: экспорт Web. Шаблон без игровых данных ещё не является готовой игрой.

C# в текущей сборке: Web не входит в поддерживаемые платформы нативного .NET-модуля, а C# export plugin не реализует Web-target. module_mono_enabled=yes не добавляет браузерную публикацию. Команды ниже не подтверждают экспорт C#-игры.

Подготовьте инструменты

Нужны SCons не ниже 4.4, Python для самого движка не ниже 3.9 и рабочий Emscripten SDK со своими дополнительными требованиями. Проверка platform/web/detect.py отклоняет Emscripten ниже 6.0.1. Это нижняя граница проверки исходников, а не обещание успешной сборки любой более новой версии.

Установите и активируйте выбранную фиксированную версию через emsdk. На Linux/macOS загрузите emsdk_env.sh в текущую shell; на Windows используйте среду emsdk/emsdk_env.bat. Настройка emsdk. Из того же терминала проверьте:

emcc --version
em++ --version
scons --version
python --version

can_build проверяет только наличие emcc в PATH. Это не проверка линковщика, всех библиотек, сети для первоначального заполнения кэша SDK или успешной компиляции. Не меняйте emsdk посреди одной партии сборок.

Соберите debug и release

Из Source, содержащего SConstruct, для первого варианта без потоков:

scons platform=web target=template_debug threads=no
scons platform=web target=template_release threads=no

Архитектура — wasm32. Ожидаемые имена ZIP для этого варианта: bin/reckfell.web.template_debug.wasm32.nothreads.zip и bin/reckfell.web.template_release.wasm32.nothreads.zip. Дополнительные параметры сборки могут добавлять суффиксы; сверяйте фактический результат, а не переименовывайте похожий старый архив.

В ZIP находятся согласованные .js, .wasm, audio worklets, HTML и файлы shell/service worker. Не переносите один .wasm, не смешивайте .js и .wasm разных сборок. Временный каталог упаковки bin/.web_zip общий: разные конфигурации в одном checkout собирайте последовательно, сохраняйте готовые ZIP отдельно.

Укажите свой ZIP в соответствующем custom debug/release template пресета игры. При установке в общий каталог шаблонов учитывайте вариант потоков и dynamic linking: переименование файла не меняет его возможности. Согласуйте шаблон с настройками экспорта и исходниками/модулями редактора.

Потоки, расширения и JavaScript

Параметр	Что меняется
`threads=no`	Вариант без pthread; не требует SharedArrayBuffer для engine threads. Это не отключение браузерных требований к WebGL, audio worklets и загрузке файлов.
`threads=yes`	Включает pthread/SharedArrayBuffer. Нужны secure context и cross-origin isolation, совместимые ресурсы и политика страницы.
`dlink_enabled=yes`	Включает WebAssembly dynamic linking для нативных расширений; добавляет `.dlink` и отдельный `.side.wasm`. Нужны Web/Wasm-версии библиотек, desktop DLL не подходит.
`javascript_eval=no`	Убирает условно подключаемую JS-библиотеку и C++-часть eval/интерфейсов. Не отключает JavaScript загрузчика, графики, ввода и аудио; это не универсальная CSP-настройка.
`proxy_to_pthread=yes`	Отдельный режим запуска main application code в worker. Требует threads; при `threads=no` или dlink конфигурация отключает этот режим.

Threads по умолчанию включены в общей конфигурации SCons. Для изолированного threaded-хостинга обычно нужны Cross-Origin-Opener-Policy: same-origin и Cross-Origin-Embedder-Policy: require-corp либо подходящий эквивалент. Проверяйте реальную страницу: crossOriginIsolated и доступность SharedArrayBuffer, а не только конфигурационный файл сервера. В iframe, при внешних ресурсах или service worker итог может отличаться. Условия cross-origin isolation.

Текущий Web-target отключает RenderingDevice; рассчитывайте на Compatibility/WebGL2, а не desktop Forward+/Mobile. Начальная WASM-память по умолчанию — 32 MiB, stack — 5120 KiB; увеличение памяти не исправляет отсутствующую поддержку target или нехватку GPU-памяти.

Web-редактор и локальная проверка

target=editor — отдельная сборка браузерного редактора, не игровой шаблон. Она получает дополнительные HTML/PWA-файлы с префиксом reckfell.editor, а минимальная начальная память принудительно повышается до 64 MiB. Не подставляйте её ZIP в игровой пресет.

После распаковки собственного результата в отдельный каталог можно использовать platform/web/serve.py. Его --root разрешается относительно platform/web, не текущего терминала; абсолютный путь исключает неоднозначность. Например, замените путь к своей распакованной сборке:

python platform/web/serve.py --root "/absolute/path/web-build" --port 8060 --no-browser

Сервер добавляет COOP/COEP-заголовки. Он может слушать не только loopback и предназначен для разработки, не production-хостинга. Откройте нужный HTML по HTTP, проверьте Console и Network: файлы не должны давать 404 или HTML вместо WASM. Очистите устаревший service-worker cache при замене набора файлов. Успешная загрузка HTML не подтверждает запуск уровня или качество рендера.

Граница проверки: настройки, состав ZIP и минимальный compiler gate сверены с исходниками. Выполнены только изолированные модели функций конфигурации/упаковки без компилятора и без записи Web-сборки. Emscripten, SCons, браузерный runtime, потоки, расширения и Web-редактор в этом обзоре не запускались; движок не менялся.