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

Update and clarify HTML5 doc

Browse Source
This commit is contained in:
L. Krause
2017-07-15 18:11:52 +02:00
parent 9c0dadd67c
commit 734db354d1
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`` ``godot.javascript.opt.zip`` for release or ``godot.javascript.opt.debug.zip``
for debug. for debug.
To install the templates, place them into the ``templates`` directory in your Finally, rename the zip archive to ``javascript_release.zip`` for the
Godot user directory. Rename the zip archive to ``javascript_release.zip`` for release template::
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:: And ``javascript_debug.zip`` for the debug template::
cp bin/godot.javascript.opt.debug.zip ~/.godot/templates/javascript_debug.zip mv bin/godot.javascript.opt.debug.zip bin/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.
Compiling to WebAssembly 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 The current default for exporting to the web is to compile to *asm.js*, a
highly optimizable subset of JavaScript. highly optimizable subset of JavaScript.
It is also possible to compile to the experimental *WebAssembly* format, which It is also possible to compile to the *WebAssembly* format, which offers better
should eventually offer better performance and loading times. Its specification performance and loading times. Running a game in this format requires a browser
is still in flux and compile tools may sporadically fail to build Godot. with WebAssembly support.
Running a game per WebAssembly requires nightly browser builds with special
flags set. As such, WebAssembly builds are currently not suitable for
publishing.
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 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 compile to asm.js similarly to the default method, then translate to
WebAssembly using a tool called ``asm2wasm``. Emscripten automatically takes WebAssembly using a tool called ``asm2wasm``. Emscripten automatically takes
care of both processes, we simply run SCons. care of both processes, we simply run SCons.
The other method uses LLVM's WebAssembly backend, which should eventually The other method uses LLVM's WebAssembly backend. This backend is not yet
produce more performant binaries. To build LLVM with this backend, set the available in release versions of LLVM, only in development builds.
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 Compiling with this backend outputs files in LLVM's ``.s`` format, which is
translated to actual WebAssembly using a tool called ``s2wasm``. Emscripten translated into actual WebAssembly using a tool called ``s2wasm``.
manages these processes as well, so we just invoke SCons. 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 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 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 These commands will build WebAssembly export templates in either release or
debug mode. The generated files' names contain ``.webassembly`` as an debug mode. The generated files' names contain ``.webassembly`` as an
additional file suffix before the extension. 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 Finally, the WebAssembly templates are renamed to ``webassembly_release.zip``
cp bin/godot.javascript.opt.debug.webassembly.zip ~/.godot/templates/javascript_debug.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 Customizing the HTML page
------------------------- -------------------------
@@ -149,32 +138,13 @@ substituted by values dependent on the export:
| Placeholder | substituted by | | Placeholder | substituted by |
+==============================+===============================================+ +==============================+===============================================+
| ``$GODOT_BASE`` | Basename of files referenced within the page, | | ``$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 | | ``$GODOT_DEBUG_ENABLED`` | ``true`` if debugging, ``false`` otherwise |
| | 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_HEAD_INCLUDE`` | Custom string to include just before the end | | ``$GODOT_HEAD_INCLUDE`` | Custom string to include just before the end |
| | of the HTML ``<head>`` element | | | 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, | | ``{{{ SCRIPT }}}`` | ``<script>`` that loads the engine, |
| | substituted only when building, not on export | | | 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 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. 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 The last placeholder is important when rewriting the ``godot_shell.html`` file
and is only substituted during build time, not during export time. and is substituted during build time rather than export.
The other placeholders are optional.

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 Users must allow **third-party** cookies when playing a game presented in an
iframe. iframe.
The ``.mem``, ``.pck`` (and ``.wasm`` when using WebAssembly) files are The other exported files are served as they are next to the ``.html`` file,
binary, usually delivered with MIME-type ``application/octet-stream``. 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 Delivering the files with gzip compression is recommended especially for the
``.pck``, ``.asm.js``, ``.mem`` and ``.wasm`` files, which are usually large in ``.pck``, ``.asm.js``, ``.mem`` and ``.wasm`` files, which are usually large in
size. The WebAssembly binary (``.wasm``) file compresses particularly well. size.
Export options 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 Turning on **Debugging Enabled** when exporting will, in addition to enabling
various debug features of the engine, display a debug output below the canvas, various debug features of the engine, display a debug output below the canvas,
displaying JavaScript and engine errors. If controls are displaying JavaScript and engine errors.
enabled as well, display of this output can be toggled.
You can also use the browser-integrated developer console, usually opened with You can also use the browser-integrated developer console, usually opened with
the F12 key, which often shows more information, including WebGL errors. 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 Web export limitations
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.
**Enable Run** will add a button between the *Stop scene* and *Play edited Scene* Exported files must not be reused
buttons in the editor to quickly open the game in the default browser for ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
testing.
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 Some functions must be called from input callbacks
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
---------------------
Browsers do not allow arbitrarily **entering full screen** at any time. The same 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 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 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 Starting exported games from the local file system
**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``.
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 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 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 ``x`` and ``y`` properties are returned as a :ref:`class_Vector2`
* Objects with an ``r``, ``g``, ``b`` and an optional ``a`` property are * Objects with an ``r``, ``g``, ``b`` and an optional ``a`` property are
returned as a :ref:`class_Color`, the JavaScript values are interpreted 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``. Any other JavaScript value is returned as ``null``.