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

Update HTML5 documentation

Browse Source 
- Update build instructions
- Update engine.js API
- Document HTML5-related feature tags
- Document JavaScript.eval() build toggle
- Warn about iOS browsers
- Warn about HTTP polling loop
This commit is contained in:
Leon Krause
2018-04-09 19:32:45 +02:00
parent 4ed62c5a45
commit c04ce7eb81
4 changed files with 71 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
development/compiling/compiling_for_web.rst
View File

@@ -13,39 +13,34 @@ To compile export templates for the Web, the following is required:
- `Emscripten 1.37.9+ <http://emscripten.org/>`__: If the version available
per package manager is not recent enough, the best alternative is to install
using the `Emscripten SDK <http://kripken.github.io/emscripten-site/docs/gettng_started/downloads.html>`__
(Install in a path without spaces, i.e. not in ``Program Files``)
- `Python 2.7+ or Python 3.5+ <https://www.python.org/>`__
- `SCons <http://www.scons.org>`__ build system
Building export templates
-------------------------
Start a terminal and set the environment variable ``EMSCRIPTEN_ROOT`` to the
installation directory of Emscripten:
Before starting, confirm that the Emscripten configuration file exists and
specifies all settings correctly. This file is available as ``~/.emscripten``
on UNIX-like systems and ``%USERPROFILE%\.emscripten`` on Windows. It's usually
written by the Emscripten SDK, e.g. when invoking ``emsdk activate latest``,
or by your package manager. It's also created when starting Emscripten's
``emcc`` program if the file doesn't exist.
If you installed Emscripten via the Emscripten SDK, declare the variable with a
path to the downloaded folder::
export EMSCRIPTEN_ROOT=~/emsdk/emscripten/master
If you installed Emscripten via package manager, the path can be retrieved with
the ``em-config`` command::
export EMSCRIPTEN_ROOT=`em-config EMSCRIPTEN_ROOT`
On Windows you can set the environment variable in the system settings or in
the command prompt::
set EMSCRIPTEN_ROOT="C:\emsdk\emscripten\master"
Now go to the root directory of the engine source code and instruct SCons to
build the JavaScript platform. Specify ``target`` as either ``release`` for a
release build or ``release_debug`` for a debug build::
Open a terminal and navigate to the root directory of the engine source code.
Then instruct SCons to build the JavaScript platform. Specify ``target`` as
either ``release`` for a release build or ``release_debug`` for a debug build::
scons platform=javascript tools=no target=release
scons platform=javascript tools=no target=release_debug
The engine will now be compiled to WebAssembly by Emscripten. If all goes well,
By default, the :ref:`JavaScript singleton <doc_javascript_eval>` will be built
into the engine. Since ``eval()`` calls can be a security concern, the
``javascript_eval`` option can be used to build without the singleton::
scons platform=javascript tools=no target=release javascript_eval=no
scons platform=javascript tools=no target=release_debug javascript_eval=no
The engine will now be compiled to WebAssembly by Emscripten. Once finished,
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.
@@ -76,10 +71,10 @@ 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
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. On Windows, make sure to escape backslashes of paths
within this file as double backslashes ``\\`` or use Unix-style paths with
a single forward slash ``/``.
Emscripten configuration file is used. 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. On Windows, make sure to escape backslashes of paths within
this file as double backslashes ``\\`` or use Unix-style paths with a single
forward slash ``/``.

30
getting_started/workflow/export/customizing_html5_shell.rst
View File

@@ -5,11 +5,19 @@ Customizing the Web export HTML page
Rather than the default HTML page that comes with the export templates, it is
also possible to use a custom HTML page. This allows drastic customization of
the final web presentation and behavior. The path to custom HTML page is
the final web presentation and behavior. The path to the custom HTML page is
specified in the export options as ``Html/Custom Html Shell``.
The default HTML page is available in the Godot Engine repository at
`/mist/dist/html/default.html <https://github.com/godotengine/godot/blob/master/misc/dist/html/default.html>`_.
Some simple use-cases where customizing the default page is useful include:
- Loading files from a different directory
- Loading a ``.zip`` file instead of a ``.pck`` file as main pack
- Loading engine files from a different directory than the main pack file
- Loading some extra files before the engine starts, so they are available in
the file system later
- Passing custom "command line" arguments, e.g. ``-s`` to start a MainLoop script
Placeholder substitution
------------------------
@@ -65,6 +73,12 @@ Returns a promise that resolves once the engine is loaded.
Unloads the module to free memory. This is called automatically once the
module is instantiated unless explicitly disabled.
``Engine.isWebGLAvailable(majorVersion = 1)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Returns ``true`` if the given major version of WebGL is available,
``false`` otherwise. Defaults to ``1`` for WebGL 1.0.
Starting an ``Engine`` instance
-------------------------------
@@ -89,15 +103,19 @@ must be passed from which the engine will be loaded.
Returns a promise that resolves once the engine is loaded and initialized.
It can then be started with ``engine.startGame()``
``engine.preloadFile(file, fileName)``
``engine.preloadFile(file, path)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This loads a file so it is available in the file system once the instance
is started. This must be called **before** starting the instance.
If ``file`` is a string, the file will be loaded from that URL and the file
name will be retained. If ``file`` is an ``ArrayBuffer`` or a view on one,
the buffer will available as a file under the name given by ``fileName``.
If ``file`` is a string, the file will be loaded from that URL. If ``file`` is
an ``ArrayBuffer`` or a view on one, the buffer will used as content of the
file.
If ``path`` is a string, it specifies the path by which the file will be
available. This is mandatory if ``file`` is not a string.
Otherwise, the path is derived from the URL of the loaded file.
Returns a promise that resolves once the file is preloaded.
@@ -209,7 +227,7 @@ argument specifying the string to print.
These methods should usually only be used in debug pages. The
``$GODOT_DEBUG_ENABLED`` placeholder can be used to check for this.
By default, ``console.log()`` and ``console.warn()`` are used respecively.
By default, ``console.log()`` and ``console.warn()`` are used respectively.
Accessing the Emscripten ``Module``
-----------------------------------

24
getting_started/workflow/export/exporting_for_web.rst
View File

@@ -8,6 +8,8 @@ This requires support for the recent technologies `WebAssembly
<http://webassembly.org/>`__ and `WebGL 2.0 <https://www.khronos.org/webgl/>`__
in the user's browser. **Firefox** and **Chromium** (Chrome, Opera) are
the most popular supported browsers, **Safari** and **Edge** do not work yet.
On **iOS**, all browsers must be based on WebKit (i.e. Safari), so they will also
not work.
Limitations
-----------
@@ -54,6 +56,7 @@ restrictions:
- Accessing or changing the ``StreamPeer`` is not possible
- Blocking mode is not available
- Cannot progress more than once per frame, so polling in a loop will freeze
- No chunked responses
- Host verification cannot be disabled
- Subject to `same-origin policy <https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy>`_
@@ -75,8 +78,9 @@ to communicate your interest.
Starting exported games from the local file system
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Many browsers will not load exported projects when **opened locally**
per ``file://`` protocol. To get around this, use a local server.
Many browsers, Chromium-based browsers specifically, 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
@@ -135,6 +139,8 @@ when using the default HTML page, 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.
.. _doc_javascript_eval:
Calling JavaScript from script
------------------------------
@@ -166,14 +172,22 @@ returned by ``eval()`` under certain circumstances:
Any other JavaScript value is returned as ``null``.
Calling ``JavaScript.eval`` on platforms other than HTML5 will also return
``null``.
HTML5 export templates may be built without support for the singleton. With such
templates, and on platforms other than HTML5, calling ``JavaScript.eval`` will
also return ``null``. The availability of the singleton can be checked with the
``JavaScript`` :ref:`feature tag <doc_feature_tags>`::
func my_func3():
if OS.has_feature('JavaScript'):
JavaScript.eval("console.log('The JavaScript singleton is available')")
else:
print("The JavaScript singleton is NOT available")
The ``eval`` method also accepts a second, optional Boolean argument, which
specifies whether to execute the code in the global execution context,
defaulting to ``false`` to prevent polluting the global namespace::
func my_func3():
func my_func4():
# execute in global execution context,
# thus adding a new JavaScript global variable `MyGlobal`
JavaScript.eval("var SomeGlobal = {};", true)

5
getting_started/workflow/export/feature_tags.rst
View File

@@ -33,7 +33,10 @@ Here is a list of most feature tags in Godot. Keep in mind they are *case sensit
+=================+========================================================+
| **Android** | Running on Android |
+-----------------+--------------------------------------------------------+
| **JavaScript** | Running on JavaScript (HTML5) |
| **HTML5** | Running on HTML5 |
+-----------------+--------------------------------------------------------+
| **JavaScript** | :ref:`JavaScript singleton <doc_javascript_eval>` is |
| | available |
+-----------------+--------------------------------------------------------+
| **OSX** | Running on macOS |
+-----------------+--------------------------------------------------------+