From 5bc874a3889c7deff379433c7c66c2d6ff984db5 Mon Sep 17 00:00:00 2001 From: eska Date: Mon, 31 Oct 2016 19:44:47 +0100 Subject: [PATCH] Document building WebAssembly export templates --- reference/compiling_for_web.rst | 106 ++++++++++++++++++++++++++------ 1 file changed, 87 insertions(+), 19 deletions(-) diff --git a/reference/compiling_for_web.rst b/reference/compiling_for_web.rst index f3650346..9dcb96cf 100644 --- a/reference/compiling_for_web.rst +++ b/reference/compiling_for_web.rst @@ -62,8 +62,8 @@ these 4 files: cp bin/godot.javascript.opt.debug.js godot.js -2. ``godot.mem`` — Another file created during compilation. This file initially - has the same name as the JavaScript file, except ``.js`` is replaced by +2. ``godot.mem`` — Also created during compilation, this file initially has the + same name as the JavaScript file, except ``.js`` is replaced by ``.html.mem``. For the release template:: @@ -74,24 +74,33 @@ these 4 files: cp bin/godot.javascript.opt.debug.html.mem godot.mem -3. ``godot.html`` and -4. ``godotfs.js`` — Both of these files are located within the Godot Engine - repository, under ``tools/html_fs/``. +3. ``godot.html`` — Another file created during compilation. This file has a + ``.html`` extension. + + For the release template:: + + cp bin/godot.javascript.opt.html godot.html + + For the debug template:: + + cp bin/godot.javascript.opt.debug.html godot.html + +4. ``godotfs.js`` — This file is located within the Godot Engine repository, + under ``/tools/dist/html_fs/``. :: - cp tools/html_fs/godot.html . - cp tools/html_fs/godotfs.js . + cp tools/dist/html_fs/godotfs.js . Once these 4 files are assembled, zip them up and your export template is ready to go. The correct name for the template file is ``javascript_release.zip`` for the release template:: - zip javascript_release godot.js godot.mem godotfs.js godot.html + zip javascript_release.zip godot.js godot.mem godotfs.js godot.html And ``javascript_debug.zip`` for the debug template:: - zip javascript_debug godot.js godot.mem godotfs.js godot.html + zip javascript_debug.zip godot.js godot.mem godotfs.js godot.html The resulting files must be placed in the ``templates`` directory in your Godot user directory:: @@ -106,12 +115,73 @@ There's no need to copy the templates in this case — you can simply reference the resulting files in your Godot source folder, so the next time you build, the custom templates will already be referenced. +Compiling to WebAssembly +------------------------- + +The current default for exporting to the web is to compile to *asm.js*, a +highly optimizable subset of JavaScript. + +It is also possible to compile to the experimental WebAssembly format, which +should eventually offer better performance and loading times. Its specification +is still in flux and compile tools may sporadically fail to build Godot. +Running a game per WebAssembly requires nightly browser builds with special +flags set. As such, WebAssembly builds are currently not suitable for +publishing. + +WebAssembly can be compiled in two ways: The default way is to first +compile to asm.js similarly to the default method, then translate to +WebAssembly using a tool called ``asm2wasm``. Emscripten automatically takes +care of both processes, we simply run SCons. + +The other method uses LLVM's WebAssembly backend, which should eventually +produce more performant binaries. To build LLVM with this backend, set the +CMake variable ``LLVM_EXPERIMENTAL_TARGETS_TO_BUILD` to ``WebAssembly`` when +building LLVM. + +Compiling with this backend outputs files in LLVM's ``.s`` format, which is +translated to actual WebAssembly using a tool called ``s2wasm``. Emscripten +manages these processes as well, so we just invoke SCons. + +In order to choose one of the two methods, the ``LLVM_ROOT`` variable in the +Emscripten configuration file ``~/.emscripten`` is set. If it points to a +directory containing binaries of Emscripten's *fastcomp* fork of clang, +``asm2wasm`` is used. This is the default in a normal Emscripten installation. +Otherwise, LLVM binaries built with the WebAssembly backend will be expected +and ``s2wasm`` is used. + +With ``LLVM_ROOT`` set up correctly, compiling to WebAssembly is as easy as +adding ``wasm=yes`` to the SCons arguments:: + + scons platform=javascript target=release wasm=yes + scons platform=javascript target=release_debug wasm=yes + +These commands will build WebAssembly binaries in either release or debug mode. +The generated files' names contain ``.webassembly`` as an additional file +suffix before the extension. + +WebAssembly builds do not use a memory initializer file, so do not add a +``godot.mem`` file in the archive — there is none. +However, the binary WebAssembly file with the ``.wasm`` extension must be +added to the archive as ``godot.wasm``. + +For the release template:: + + cp bin/godot.javascript.opt.webassembly.wasm godot.wasm + +For the debug template:: + + cp bin/godot.javascript.opt.debug.webassembly.wasm godot.wasm + +The WebAssembly export templates simply replace the previous asm.js-based web +export templates with the names ``javascript_release.zip`` and +``javascript_debug.zip`` + Customizing the HTML page ------------------------- -Rather than the default ``godot.html`` file from the Godot Engine repository's -``tools/html_fs/`` directory, it is also possible to use a custom HTML page. -This allows drastic customization of the final web presentation. +Rather than the default ``godot.html`` file generated when compiling, it is +also possible to use a custom HTML page. This allows drastic customization of +the final web presentation. The JavaScript object ``Module`` is the page's interface to Emscripten. Check the official documentation for information on how to use it: https://kripken.github.io/emscripten-site/docs/api_reference/module.html @@ -126,13 +196,11 @@ substituted by values dependent on the export: +------------------------------+-----------------------------------------------+ | Placeholder | substituted by | +==============================+===============================================+ -| ``$GODOT_JS`` | Name of the compiled Godot Engine JavaScript | -| | file | +| ``{{{ SCRIPT }}}`` | ``