godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2026-01-07 02:12:07 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #409 from eska014/web-doc

Browse Source 
Update and clarify HTML5 doc
This commit is contained in:
Rémi Verschelde
2017-07-15 20:10:57 +02:00
committed by GitHub
parent 88109e57d8 734db354d1
commit cf6f2ad1b2
2 changed files with 73 additions and 95 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
development/compiling/compiling_for_web.rst
View File

@@ -43,22 +43,14 @@ the resulting file will be placed in the ``bin`` subdirectory. Its name is
``godot.javascript.opt.zip`` for release or ``godot.javascript.opt.debug.zip``
for debug.
To install the templates, place them into the ``templates`` directory in your
Godot user directory. Rename the zip archive to ``javascript_release.zip`` for
the release template::
Finally, rename the zip archive to ``javascript_release.zip`` for the
release template::
cp bin/godot.javascript.opt.zip ~/.godot/templates/javascript_release.zip
mv bin/godot.javascript.opt.zip bin/javascript_release.zip
And ``javascript_debug.zip`` for the debug template::
cp bin/godot.javascript.opt.debug.zip ~/.godot/templates/javascript_debug.zip
If you are writing custom modules or using custom C++ code, you may want to
configure your zip files as custom export templates. This can be done in the
export GUI, using the "Custom Package" option.
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.
mv bin/godot.javascript.opt.debug.zip bin/javascript_debug.zip
Compiling to WebAssembly
-------------------------
@@ -66,28 +58,24 @@ 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.
It is also possible to compile to the *WebAssembly* format, which offers better
performance and loading times. Running a game in this format requires a browser
with WebAssembly support.
Compiling to WebAssembly requires using the `incoming branch of Emscripten <http://kripken.github.io/emscripten-site/docs/building_from_source/building_emscripten_from_source_using_the_sdk.html#building-emscripten-from-the-main-repositories>`_.
Compiling to WebAssembly requires using the latest version of Emscripten.
If your OS does not offer up-to-date packages for Emscripten, the easiest way
is usually to install using Emscripten's `emsdk <http://kripken.github.io/emscripten-site/docs/getting_started/downloads.html>`_.
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.
The other method uses LLVM's WebAssembly backend. This backend is not yet
available in release versions of LLVM, only in development builds.
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.
translated into 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
@@ -107,11 +95,12 @@ adding ``wasm=yes`` to the SCons arguments::
These commands will build WebAssembly export templates in either release or
debug mode. The generated files' names contain ``.webassembly`` as an
additional file suffix before the extension.
The templates simply replace the previous asm.js-based web export templates
with the names ``javascript_release.zip`` and ``javascript_debug.zip``::
cp bin/godot.javascript.opt.webassembly.zip ~/.godot/templates/javascript_release.zip
cp bin/godot.javascript.opt.debug.webassembly.zip ~/.godot/templates/javascript_debug.zip
Finally, the WebAssembly templates are renamed to ``webassembly_release.zip``
and ``webassembly_debug.zip``::
mv bin/godot.javascript.opt.webassembly.zip bin/webassembly_release.zip
mv bin/godot.javascript.opt.debug.webassembly.zip bin/webassembly_debug.zip
Customizing the HTML page
-------------------------
@@ -149,32 +138,13 @@ substituted by values dependent on the export:
| Placeholder | substituted by |
+==============================+===============================================+
| ``$GODOT_BASE`` | Basename of files referenced within the page, |
| | without file extension or other suffixes |
| | without suffixes |
+------------------------------+-----------------------------------------------+
| ``$GODOT_CANVAS_WIDTH`` | Integer specifying the initial display width |
| | of the game |
+------------------------------+-----------------------------------------------+
| ``$GODOT_CANVAS_HEIGHT`` | Integer specifying the initial display height |
| | of the game |
+------------------------------+-----------------------------------------------+
| ``$GODOT_DEBUG_ENABLED`` | String ``true`` if debugging, ``false`` |
| | otherwise |
+------------------------------+-----------------------------------------------+
| ``$GODOT_CONTROLS_ENABLED`` | String ``true`` if ``html/controls_enabled`` |
| | is enabled, ``false`` otherwise |
+------------------------------+-----------------------------------------------+
| ``$GODOT_HEAD_TITLE`` | Title of the page, normally used as content |
| | of the HTML ``<title>`` element |
| ``$GODOT_DEBUG_ENABLED`` | ``true`` if debugging, ``false`` otherwise |
+------------------------------+-----------------------------------------------+
| ``$GODOT_HEAD_INCLUDE`` | Custom string to include just before the end |
| | of the HTML ``<head>`` element |
+------------------------------+-----------------------------------------------+
| ``$GODOT_STYLE_FONT_FAMILY`` | CSS format ``font-family`` to use, without |
| | terminating semicolon |
+------------------------------+-----------------------------------------------+
| ``$GODOT_STYLE_INCLUDE`` | Custom string to include just before the end |
| | of the page's CSS |
+------------------------------+-----------------------------------------------+
| ``{{{ SCRIPT }}}`` | ``<script>`` that loads the engine, |
| | substituted only when building, not on export |
+------------------------------+-----------------------------------------------+
@@ -182,5 +152,4 @@ substituted by values dependent on the export:
The first three of the placeholders listed should always be implemented in the
HTML page, since they are important for the correct presentation of the game.
The last placeholder is important when rewriting the ``godot_shell.html`` file
and is only substituted during build time, not during export time.
The other placeholders are optional.
and is substituted during build time rather than export.

93
learning/workflow/export/exporting_for_web.rst
View File

@@ -21,68 +21,76 @@ It can also be inserted into another HTML file as an ``<iframe>`` element.
Users must allow **third-party** cookies when playing a game presented in an
iframe.
The ``.mem``, ``.pck`` (and ``.wasm`` when using WebAssembly) files are
binary, usually delivered with MIME-type ``application/octet-stream``.
The other exported files are served as they are next to the ``.html`` file,
names unchanged.
The ``.mem`` and ``.pck`` files are binary, usually delivered with the
MIME-type ``application/octet-stream``. The ``.wasm`` file is the WebAssembly
module, delivered as ``application/wasm``.
Delivering the files with gzip compression is recommended especially for the
``.pck``, ``.asm.js``, ``.mem`` and ``.wasm`` files, which are usually large in
size. The WebAssembly binary (``.wasm``) file compresses particularly well.
size.
Export options
--------------
If a runnable web export template is available, a button appears between the
*Stop scene* and *Play edited Scene* buttons in the editor to quickly open the
game in the default browser for testing.
**Target** sets the format of the engine. *WebAssembly* is a newer and more
performant technology that is only supported by recent browser versions.
*asm.js* is a highly optimizable subset of JavaScript and supported by some
older browser versions. A 64-bit browser is required to run games in asm.js
format. Most notably, this is a problem with Firefox, which on Windows is
shipped as a 32-bit application by default.
For asm.js **Memory Size** is fixed and must thus be set during export. Try
using no more than necessary to strain users' browsers as little as possible.
For WebAssembly, memory growth is enabled, so this option is not needed nor
displayed.
**Head Include** is appended into the ``<head>`` element of the generated
HTML page. This allows, for example, linking web fonts for use in the page.
Turning on **Debugging Enabled** when exporting will, in addition to enabling
various debug features of the engine, display a debug output below the canvas,
displaying JavaScript and engine errors. If controls are
enabled as well, display of this output can be toggled.
displaying JavaScript and engine errors.
You can also use the browser-integrated developer console, usually opened with
the F12 key, which often shows more information, including WebGL errors.
**Memory Size** is fixed and must thus be set during export. Try using no more
than necessary to strain users' browsers as little as possible.
For WebAssembly builds, memory growth is enabled, so this only sets the
initially allocated amount, which will grow as needed.
Web export limitations
----------------------
**Enable Run** will add a button between the *Stop scene* and *Play edited Scene*
buttons in the editor to quickly open the game in the default browser for
testing.
Exported files must not be reused
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The remaining options customize the generated HTML page:
The exported files ending with ``.html`` and ``fs.js`` are adjusted on export
specifically for that game's version and the given export options. They must
not be reused in futher exports.
**Title** is the content of the ``<title>`` element of the page, usually used by
browsers as the tab and window name. The title set here is only displayed until
the game is started, afterwards the title is set to the application name set in
the project settings.
**Head Include** and **Style Include** are appended into the ``<head>`` and
CSS ``<style>`` elements respectively. This allows, for example, linking
web fonts for use in the page.
**Font Family** is the CSS ``font-family`` used on the page, without terminating
semicolon.
**Controls Enabled** toggles display of controls, offering e.g. a toggle for
output display in debug mode and a fullscreen button.
In the default page, the controls are displayed in the top-right corner on top
of the canvas, which can get in the way in games that use the cursor.
Security restrictions
---------------------
Some functions must be called from input callbacks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Browsers do not allow arbitrarily **entering full screen** at any time. The same
goes for **capturing the cursor**. Instead, these actions have to occur as a
response to a JavaScript input event. In Godot, this is most easily done by
entering full screen from within an ``_input()`` callback.
entering full screen from within an input callback such ``_input`` or
``_unhandled_input``.
Chromium-derived browsers will not load exported projects when
**opened locally** per ``file://`` protocol. To get around this, you can start
the browser with the ``--allow-file-access-from-files`` flag, or use a local
server. Python offers an easy way for this, using ``python -m SimpleHTTPServer``
with Python 2 or ``python -m http.server`` with Python 3 will serve the
current working directory on ``http://localhost:8000``.
Starting exported games from the local file system
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Locale
------
Many browsers will not load exported projects when **opened locally**
per ``file://`` protocol. To get around this, use a local server.
Python offers an easy method for this, using ``python -m SimpleHTTPServer``
with Python 2 or ``python -m http.server`` with Python 3 will serve the current
working directory on ``http://localhost:8000``.
Locale lookup
~~~~~~~~~~~~~
Godot tries to detect the user's locale using information provided by the
browser, but this is rather unreliable. A better way is to use CGI to read the
@@ -130,7 +138,8 @@ value and returned by ``eval()`` under certain circumstances:
* Objects with ``x`` and ``y`` properties are returned as a :ref:`class_Vector2`
* Objects with an ``r``, ``g``, ``b`` and an optional ``a`` property are
returned as a :ref:`class_Color`, the JavaScript values are interpreted
as 8-bit values (0-255)
as 8-bit values (0-255) for the color components and
floating point values (0.0-1.0) for the alpha channel
Any other JavaScript value is returned as ``null``.