diff --git a/development/compiling/compiling_for_web.rst b/development/compiling/compiling_for_web.rst index 1ddc9921a..4cd5fc578 100644 --- a/development/compiling/compiling_for_web.rst +++ b/development/compiling/compiling_for_web.rst @@ -13,39 +13,34 @@ To compile export templates for the Web, the following is required: - `Emscripten 1.37.9+ `__: If the version available per package manager is not recent enough, the best alternative is to install using the `Emscripten SDK `__ - (Install in a path without spaces, i.e. not in ``Program Files``) - `Python 2.7+ or Python 3.5+ `__ - `SCons `__ 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 ` 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 ``/``. diff --git a/getting_started/workflow/export/customizing_html5_shell.rst b/getting_started/workflow/export/customizing_html5_shell.rst index 53e00a2d2..f51a0a1c5 100644 --- a/getting_started/workflow/export/customizing_html5_shell.rst +++ b/getting_started/workflow/export/customizing_html5_shell.rst @@ -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 `_. +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`` ----------------------------------- diff --git a/getting_started/workflow/export/exporting_for_web.rst b/getting_started/workflow/export/exporting_for_web.rst index 87c2be453..062b304e0 100644 --- a/getting_started/workflow/export/exporting_for_web.rst +++ b/getting_started/workflow/export/exporting_for_web.rst @@ -8,6 +8,8 @@ This requires support for the recent technologies `WebAssembly `__ and `WebGL 2.0 `__ 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 `_ @@ -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 `:: + + 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) diff --git a/getting_started/workflow/export/feature_tags.rst b/getting_started/workflow/export/feature_tags.rst index 214020b80..faf0beb41 100644 --- a/getting_started/workflow/export/feature_tags.rst +++ b/getting_started/workflow/export/feature_tags.rst @@ -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 ` is | +| | available | +-----------------+--------------------------------------------------------+ | **OSX** | Running on macOS | +-----------------+--------------------------------------------------------+