stan220/godot-docs
1
0
Fork 0
mirror of https://github.com/stan220/godot-docs.git synced 2026-09-08 18:29:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #4798 from Faless/js/3.3_backports

Browse Source 
[3.3] [HTML5] Backport HTML5 changes from master
This commit is contained in:
Rémi Verschelde
2021-03-31 20:08:03 +02:00
committed by GitHub
parent 0b715e3321 8f2590e8a2
commit 4daaf37027
3 changed files with 253 additions and 173 deletions
Download Patch File Download Diff File Expand all files Collapse all files
development/compiling/compiling_for_web.rst
+47 -27
View File
@@ -10,7 +10,7 @@ Requirements
To compile export templates for the Web, the following is required:
- `Emscripten 1.39.0+ <https://emscripten.org>`__.
- `Emscripten 1.39.9+ <https://emscripten.org>`__.
- `Python 3.5+ <https://www.python.org/>`__.
- `SCons 3.0+ <https://www.scons.org>`__ build system.
@@ -20,16 +20,9 @@ To compile export templates for the Web, the following is required:
Building export templates
-------------------------
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.
.. attention:: On Windows, make sure to escape backslashes of paths within the Emscripten
configuration file as double backslashes ``\\`` or use Unix-style paths with a
single forward slash ``/``.
Before starting, confirm that ``emcc`` is available in your PATH. This is
usually configured by the Emscripten SDK, e.g. when invoking ``emsdk activate``
and ``source ./emsdk_env.sh``/``emsdk_env.bat``.
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
@@ -60,22 +53,49 @@ And ``webassembly_debug.zip`` for the debug template::
mv bin/godot.javascript.opt.debug.zip bin/webassembly_debug.zip
Building per asm.js translation or LLVM backend
-----------------------------------------------
Threads and GDNative
--------------------
WebAssembly can be compiled in two ways: The default is to first compile to
asm.js, a highly optimizable subset of JavaScript, using Emscripten's
*fastcomp* fork of LLVM. This code is then translated to WebAssembly using a
tool called ``asm2wasm``. Emscripten automatically takes care of both
processes, we simply run SCons.
The default export templates do not include threads and GDNative support for
performance and compatibility reasons. See the
:ref:`export page <doc_javascript_export_options>` for more info.
The other method uses LLVM's WebAssembly backend. This backend is available
starting with LLVM 8 or in development builds.
Emscripten manages this process as well, so we just invoke SCons.
You can build the export templates using the option ``threads_enabled=yes`` or
``gdnative_enabled=yes`` to enable threads or GDNative support::
In order to choose one of the two methods, the ``LLVM_ROOT`` variable in the
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
the LLVM's WebAssembly backend is used.
scons platform=javascript tools=no threads_enabled=yes target=release
scons platform=javascript tools=no threads_enabled=yes target=release_debug
scons platform=javascript tools=no gdnative_enabled=yes target=release
scons platform=javascript tools=no gdnative_enabled=yes target=release_debug
Once finished, the resulting file will be placed in the ``bin`` subdirectory.
Its name will have either the ``.threads`` or ``.gdnative`` suffix.
Finally, rename the zip archives to ``webassembly_release_threads.zip`` and
``webassembly_release_gdnative.zip`` for the release template::
mv bin/godot.javascript.opt.threads.zip bin/webassembly_threads_release.zip
mv bin/godot.javascript.opt.gdnative.zip bin/webassembly_gdnative_release.zip
And ``webassembly_debug_threads.zip`` and ``webassembly_debug_gdnative.zip`` for
the debug template::
mv bin/godot.javascript.opt.debug.threads.zip bin/webassembly_threads_debug.zip
mv bin/godot.javascript.opt.debug.gdnative.zip bin/webassembly_gdnative_debugzip
Building the Editor
-------------------
It is also possible to build a version of the Godot editor that can run in the
browser. The editor version requires threads support and is not recommended
over the native build. You can build the editor with::
scons platform=javascript tools=yes threads_enabled=yes target=release_debug
Once finished, the resulting file will be placed in the ``bin`` subdirectory.
Its name will be ``godot.javascript.opt.tools.threads.zip``. You can upload the
zip content to your web server and visit it with your browser to use the editor.
Refer to the :ref:`export page <doc_javascript_export_options>` for the web
server requirements.
getting_started/workflow/export/exporting_for_web.rst
+108 -54
View File
@@ -12,27 +12,11 @@ in the user's browser.
with :kbd:`F12`, to view **debug information** like JavaScript,
engine, and WebGL errors.
.. attention:: Many browsers, including Firefox and Chromium-based browsers,
will not load exported projects when **opened locally** per
``file://`` protocol. To get around this, use a local server.
.. tip:: Python offers an easy method to start a local server.
Use ``python -m http.server 8000 --bind 127.0.0.1`` with Python 3 to serve the
current working directory at ``http://localhost:8000``.
`Refer to MDN for additional information <https://developer.mozilla.org/en-US/docs/Learn/Common_questions/set_up_a_local_testing_server>`__.
.. attention:: `There are significant bugs when running HTML5 projects on iOS <https://github.com/godotengine/godot/issues/26554>`__
.. attention:: `There are significant bugs when running HTML5 projects on iOS <https://github.com/godotengine/godot/issues?q=is:issue+is:open+label:platform:html5+ios>`__
(regardless of the browser). We recommend using
:ref:`iOS' native export functionality <doc_exporting_for_ios>`
instead, as it will also result in better performance.
.. note::
If you use Linux, due to
`poor Firefox WebGL performance <https://bugzilla.mozilla.org/show_bug.cgi?id=1010527>`__,
it's recommended to play the exported project using a Chromium-based browser
instead of Firefox.
WebGL 2
-------
@@ -49,6 +33,43 @@ WebKit (i.e. Safari), so they will also not work.
Godot's WebGL 2 renderer has issues with 3D and is no longer maintained.
.. _doc_javascript_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.
You can choose the **Export Type** to select which features will be available:
- *Regular*: is the most compatible across browsers, will not support threads, nor GDNative.
- *Threads*: will require the browser to support `SharedArrayBuffer <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer>`__
- *GDNative*: enables GDNative support but makes the binary bigger and slower to load.
If you plan to use :ref:`VRAM compression <doc_import_images>` make sure that
**Vram Texture Compression** is enabled for the targeted platforms (enabling
both **For Desktop** and **For Mobile** will result in a bigger, but more
compatible export).
If a path to a **Custom HTML shell** file is given, it will be used instead of
the default HTML page. See :ref:`doc_customizing_html5_shell`.
**Head Include** is appended into the ``<head>`` element of the generated
HTML page. This allows to, for example, load webfonts and third-party
JavaScript APIs, include CSS, or run JavaScript code.
.. important:: Each project must generate their own HTML file. On export,
several text placeholders are replaced in the generated HTML
file specifically for the given export options. Any direct
modifications to that HTML file will be lost in future exports.
To customize the generated file, use the **Custom HTML shell**
option.
.. warning:: **Export types** other then *Regular* are not yet supported by the
C# version.
Limitations
-----------
@@ -56,6 +77,19 @@ For security and privacy reasons, many features that work effortlessly on
native platforms are more complicated on the web platform. Following is a list
of limitations you should be aware of when porting a Godot game to the web.
.. _doc_javascript_secure_contexts:
.. important:: Browser vendors are making more and more functionalities only
available in `secure contexts <https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts>`_,
this means that such features are only be available if the web
page is served via a secure HTTPS connection (localhost is
usually exempt from such requirement).
.. tip:: Check the `list of open HTML5 issues on GitHub
<https://github.com/godotengine/godot/issues?q=is:open+is:issue+label:platform:html5>`__
to see if the functionality you're interested in has an issue yet. If
not, open one to communicate your interest.
Using cookies for data persistence
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -68,6 +102,26 @@ The method ``OS.is_userfs_persistent()`` can be used to check if the
``user://`` file system is persistent, but can give false positives in some
cases.
Threads
~~~~~~~
As mentioned :ref:`above <doc_javascript_export_options>` multi-threading is
only available if the appropriate **Export Type** is set and support for it
across browsers is still limited.
.. warning:: Requires a :ref:`secure context <doc_javascript_secure_contexts>`.
Browsers are also starting to require that the web page is served with specific
`cross-origin isolation headers <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy>`__.
GDNative
~~~~~~~~
As mentioned :ref:`above <doc_javascript_export_options>` GDNative is only
available if the appropriate **Export Type** is set.
The export will also copy the required GDNative ``.wasm`` files to the output
folder (and must be uploaded to your server along with your game).
Full screen and mouse capture
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -82,8 +136,8 @@ For the same reason, the full screen project setting doesn't work unless the
engine is started from within a valid input event handler. This requires
:ref:`customization of the HTML page <doc_customizing_html5_shell>`.
Audio autoplay
~~~~~~~~~~~~~~
Audio
~~~~~
Chrome restricts how websites may play audio. It may be necessary for the
player to click or tap or press a key to enable audio.
@@ -91,10 +145,20 @@ player to click or tap or press a key to enable audio.
.. seealso:: Google offers additional information about their `Web Audio autoplay
policies <https://sites.google.com/a/chromium.org/dev/audio-video/autoplay>`__.
:ref:`class_HTTPClient` and :ref:`class_HTTPRequest`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. warning:: Access to microphone requires a
:ref:`secure context <doc_javascript_secure_contexts>`.
The HTTP classes have several restrictions on the HTML5 platform:
Networking
~~~~~~~~~~
Low level networking is not implemented due to lacking support in browsers.
Currently, only :ref:`HTTP client <doc_http_client_class>`,
:ref:`HTTP requests <doc_http_request_class>`,
:ref:`WebSocket (client) <doc_websocket>` and :ref:`WebRTC <doc_webrtc>` are
supported.
The HTTP classes also have several restrictions on the HTML5 platform:
- Accessing or changing the ``StreamPeer`` is not possible
- Threaded/Blocking mode is not available
@@ -103,11 +167,26 @@ The HTTP classes have several restrictions on the HTML5 platform:
- Host verification cannot be disabled
- Subject to `same-origin policy <https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy>`__
Exported ``.html`` file must not be reused
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Clipboard
~~~~~~~~~
Each project must generate their own HTML file. On export, several text placeholders are replaced in the **generated HTML
file** specifically for the given export options. Any direct modifications to the **generated HTML file** will be lost in future exports. To customize the generated file, see :ref:`doc_customizing_html5_shell`.
Clipboard synchronization between engine and the operating system requires a
browser supporting the `Clipboard API <https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API>`__,
additionally, due to the API asynchronous nature might not be reliable when
accessed from GDScript.
.. warning:: Requires a :ref:`secure context <doc_javascript_secure_contexts>`.
Gamepads
~~~~~~~~
Gamepads will not be detected until one of their button is pressed. Gamepads
might have the wrong mapping depending on the browser/OS/gamepad combination,
sadly the `Gamepad API <https://developer.mozilla.org/en-US/docs/Web/API/Gamepad_API/Using_the_Gamepad_API>`__
does not provide a reliable way to detect the gamepad information necessary
to remap them based on model/vendor/OS due to privacy considerations.
.. warning:: Requires a :ref:`secure context <doc_javascript_secure_contexts>`.
Boot splash is not displayed
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -122,22 +201,6 @@ Shader language limitations
When exporting a GLES2 project to HTML5, WebGL 1.0 will be used. WebGL 1.0
doesn't support dynamic loops, so shaders using those won't work there.
Unimplemented functionality
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following functionality is currently unavailable on the HTML5 platform:
- Threads
- GDNative
- C#
- Clipboard synchronization between engine and operating system
- Networking other than :ref:`class_HTTPClient` and :ref:`class_WebSocketClient`
.. tip:: Check the `list of open HTML5 issues on GitHub
<https://github.com/godotengine/godot/issues?q=is:open+is:issue+label:platform:html5>`__
to see if the functionality you're interested in has an issue yet. If
not, open one to communicate your interest.
Serving the files
-----------------
@@ -174,19 +237,10 @@ the ``.pck`` and ``.wasm`` files, which are usually large in size.
The WebAssembly module compresses particularly well, down to around a quarter
of its original size with gzip compression.
Export options
--------------
**Hosts that provide on-the-fly compression:** GitHub Pages (gzip)
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.
If a path to a **Custom HTML shell** file is given, it will be used instead of
the default HTML page. See :ref:`doc_customizing_html5_shell`.
**Head Include** is appended into the ``<head>`` element of the generated
HTML page. This allows to, for example, load webfonts and third-party
JavaScript APIs, include CSS, or run JavaScript code.
**Hosts that don't provide on-the-fly compression:** itch.io, GitLab Pages
(`supports manual gzip precompression <https://webd97.de/post/gitlab-pages-compression/>`__)
.. _doc_javascript_eval:
tutorials/platform/customizing_html5_shell.rst
+98 -92
View File
@@ -5,7 +5,7 @@ Custom HTML page for Web export
While Web export templates provide a default HTML page fully capable of launching
the project without any further customization, it may be beneficial to create a custom
HTML page. While the game itself cannot be directly controlled from the outside,
HTML page. While the game itself cannot easily be directly controlled from the outside yet,
such page allows to customize the initialization process for the engine.
Some use-cases where customizing the default page is useful include:
@@ -20,32 +20,48 @@ Some use-cases where customizing the default page is useful include:
The default HTML page is available in the Godot Engine repository at
`/misc/dist/html/full-size.html <https://github.com/godotengine/godot/blob/master/misc/dist/html/full-size.html>`__
and can be used as a reference implementation. Another sample HTML page is available at
`/misc/dist/html/fixed-size.html <https://github.com/godotengine/godot/blob/master/misc/dist/html/fixed-size.html>`__.
It differs from the default one by having a fixed size canvas area and an output widget below it.
but the following template can be used as a much simpler example:
.. note:: It is recommended to use developer tools provided by browser vendors to debug
exported projects. Output generated by the engine may be limited and does not
include WebGL errors.
.. code-block:: html
<!DOCTYPE html>
<html>
<head>
<title>My Template</title>
<meta charset="UTF-8">
</head>
<body>
<canvas id="canvas"></canvas>
<script src="$GODOT_URL"></script>
<script>
var engine = new Engine($GODOT_CONFIG);
engine.startGame();
</script>
</body>
</html>
Setup
-----
As evident by the default HTML page, it is mostly a regular HTML document. To work with
Godot projects it needs to be fully realized, to have a control code that calls
the :js:class:`Engine` class, and to provide places for several placeholders, which are
replaced with their actual values during export.
As shown by the example above, it is mostly a regular HTML document, with few placeholders
which needs to be replaced during export, an html ``<canvas>`` element, and some simple
JavaScript code that calls the :js:class:`Engine` class.
.. image:: img/html5_export_options.png
The only required placeholders are:
- ``$GODOT_BASENAME``:
The base name from the *Export Path*, as set up in the export options; suffixes are omitted
(e.g. ``game.html`` becomes ``game``). This variable can be used to generate a path
to the main JavaScript file ``$GODOT_BASENAME.js``, which provides the :js:class:`Engine`
class. A splash image shown during the booting process can be accessed using this variable
as well: ``$GODOT_BASENAME.png``.
- ``$GODOT_URL``:
The name of the main JavaScript file, which provides the :js:class:`Engine` class required
to start the engine and that must be included in the HTML as a ``<script>``.
The name is generated from the *Export Path* during the export process.
- ``$GODOT_CONFIG``:
A JavaScript object, containing the export options and can be later overridden.
See :js:attr:`EngineConfig` for the full list of overrides.
The following optional placeholders will enable some extra features in your cusstom HTML template.
- ``$GODOT_PROJECT_NAME``:
The project name as defined in the Project Settings.
The project name as defined in the Project Settings. It is a good idea to use it as a ``<title>``
in your template.
- ``$GODOT_HEAD_INCLUDE``:
A custom string to include in the HTML document just before the end of the ``<head>`` tag. It
@@ -53,66 +69,74 @@ replaced with their actual values during export.
control the HTML page you create, this variable can be useful for configuring parts of the
HTML ``head`` element from the Godot Editor, e.g. for different Web export presets.
- ``$GODOT_DEBUG_ENABLED``:
A flag that tells if this is a debug build, or not. This variable is substituted by strings
``true`` and ``false``, and can be used to disable debug branches within your control code.
When the custom page is ready, it can be selected in the export options under the *Html / Custom Html Shell*
section.
.. image:: img/html5_export_options.png
Starting the project
--------------------
To be able to start the game, you need to write a script that initializes the engine — the control
code. This process consists of three steps, though some of them can be skipped and left for
a default behavior.
code. This process consists of three steps, though as shown most of them can be skipped depending on
how much customization is needed (or be left to a default behavior).
See the :ref:`HTML5 shell class reference <doc_html5_shell_classref>`, for the full list of methods and options available.
First, the engine must be loaded, then it needs to be initialized, and after this the project
can finally be started. You can perform every of these steps manually and with great control.
However, in the simplest case all you need to do is to create an instance of the :js:class:`Engine`
class and then call the :js:meth:`engine.startGame` method.
class with the exported configuration, and then call the :js:meth:`engine.startGame <Engine.prototype.startGame>` method
optionally overriding any :js:attr:`EngineConfig` parameters.
.. code-block:: js
const execName = "path://to/executable"
const mainPack = "path://to/main_pack"
const engine = new Engine();
engine.startGame(execName, mainPack)
const engine = new Engine($GODOT_CONFIG);
engine.startGame({
/* optional override configuration, eg. */
// unloadAfterInit: false,
// canvasResizePolicy: 0,
// ...
});
This snippet of code automatically loads and initializes the engine before starting the game.
It uses the given path to the executable to deduce the path to load the engine. The :js:meth:`engine.startGame`
It uses the given configuration to to load the engine. The :js:meth:`engine.startGame <Engine.prototype.startGame>`
method is asynchronous and returns a ``Promise``. This allows your control code to track if
the game was loaded correctly without blocking execution or relying on polling.
In case your project needs to have special arguments passed to it by the start-up script,
:js:meth:`engine.startGame` can be replaced by :js:meth:`engine.start`. This method takes an
arbitrary list of string arguments. As it does not have a defined list of arguments, :js:meth:`engine.start`
cannot automatically load the engine.
In case your project needs to have special control over the start arguments and dependency files,
the :js:meth:`engine.start <Engine.prototype.start>` method can be used instead. Note, that this method do not
automatically preload the ``pck`` file, so you will probably want to manually preload it
(and any other extra file) via the :js:meth:`engine.preloadFile <Engine.prototype.preloadFile>` method.
To load the engine manually the :js:meth:`Engine.load` static method must be called. As
this method is static, multiple engine instances can be spawned with the exact same ``basePath``.
If an instance requires a different ``basePath``, you can call the :js:meth:`engine.init`
method with that path before starting the game.
Optionally, you can also manually :js:meth:`engine.init <Engine.prototype.init>` to perform specific actions after
the module initialization, but before the engine starts.
.. note:: Multiple instances cannot be spawned by default, as the engine is immediately unloaded after it is initialized.
To prevent this from happening the :js:meth:`engine.setUnloadAfterInit` method can be called. It is still possible
to unload the engine manually afterwards by calling the :js:meth:`Engine.unload` static method. Unloading the engine
frees browser memory by unloading files that are no longer needed once the instance is initialized.
To correctly load the engine on some hosting providers and network configurations you may
need to change the default filename extension by using :js:meth:`Engine.setWebAssemblyFilenameExtension`.
By default, the extension is assumed to be ``wasm``. If your hosting provider blocks this
extension, this static method can be used to change it to something that is supported.
This process is a bit more complex, but gives you full control over the engine startup process.
.. code-block:: js
Engine.setWebAssemblyFilenameExtension("dat");
// Load mygame.dat as WebAssembly module.
Engine.load("mygame");
const myWasm = 'mygame.wasm';
const myPck = 'mygame.pck';
const engine = new Engine();
Promise.all([
// Load and init the engine
engine.init(myWasm),
// And the pck concurrently
engine.preloadFile(myPck),
]).then(() => {
// Now start the engine.
return engine.start({ args: ['--main-pack', myPck] });
}).then(() => {
console.log('Engine has started!');
});
.. warning:: If a different filename extension is used, some web servers may automatically
set the MIME-type of the file to something other than :mimetype:`application/wasm`.
In that case some start-up optimizations may be skipped.
To load the engine manually the :js:meth:`Engine.load` static method must be called. As
this method is static, multiple engine instances can be spawned if the share the same ``wasm``.
.. note:: Multiple instances cannot be spawned by default, as the engine is immediately unloaded after it is initialized.
To prevent this from happening see the :js:attr:`unloadAfterInit` override option. It is still possible
to unload the engine manually afterwards by calling the :js:meth:`Engine.unload` static method. Unloading the engine
frees browser memory by unloading files that are no longer needed once the instance is initialized.
Customizing the behavior
------------------------
@@ -125,46 +149,40 @@ allows to test for a specific major version of WebGL.
As the real executable file does not exist in the Web environment, the engine only stores a virtual
filename formed from the base name of loaded engine files. This value affects the output of the
:ref:`OS.get_executable_path() <class_OS_method_get_executable_path>` method and defines the name of
the automatically started main pack. The :js:meth:`engine.setExecutableName` method can be used
to override this value.
If your project requires some files to be available the moment it is loaded, you can preload
them by calling the :js:meth:`engine.preloadFile` method with a path to a file or by providing it
with an ``ArrayBuffer`` object. In case of the ``ArrayBuffer``, or one of its views, a second argument
must be specified to define an internal path for the loaded resource.
the automatically started main pack. The :js:attr:`executable` override option can be
used to override this value.
Customizing the presentation
----------------------------
Several methods can be used to further customize the look and behavior of the game on your page.
Several configuration options can be used to further customize the look and behavior of the game on your page.
By default, the first canvas element on the page is used for rendering. To use a different canvas
element the :js:meth:`engine.setCanvas` method can be used. It requires a reference to the DOM
element the :js:attr:`canvas` override option can be used. It requires a reference to the DOM
element itself.
.. code-block:: js
const canvasElement = document.querySelector("#my-canvas-element");
engine.setCanvas(canvasElement);
engine.startGame({ canvas: canvasElement });
If the width and height of this canvas element differ from values set in the project settings, it
will be resized on the project start. This behavior can be disabled by calling the :js:meth:`engine.setCanvasResizedOnStart`
method.
The way the engine resize the canvas can be configured via the :js:attr:`canvasResizePolicy`
override option.
If your game takes some time to load, it may be useful to display a custom loading UI which tracks
the progress. This can be achieved with the :js:meth:`engine.setProgressFunc` method which allows
to set up a callback function to be called regularly as the engine loads new bytes.
the progress. This can be achieved with the :js:attr:`onProgress` callback option, which
allows to set up a callback function that will be called regularly as the engine loads new bytes.
.. code-block:: js
function printProgress(current, total) {
console.log("Loaded " + current + " of " + total + " bytes");
}
engine.setProgressFunc(printProgress);
engine.startGame({ onProgress: printProgress });
Be aware that in some cases ``total`` can be ``0``. This means that it cannot be calculated.
If your game supports multiple languages, the :js:meth:`engine.setLocale` method can be used to set
a specific locale, provided you have a valid language code string. It may be good to use server-side
If your game supports multiple languages, the :js:attr:`locale` override option can be used to
force a specific locale, provided you have a valid language code string. It may be good to use server-side
logic to determine which languages a user may prefer. This way the language code can be taken from the
``Accept-Language`` HTTP header, or determined by a GeoIP service.
@@ -175,30 +193,18 @@ by the engine. This is similar to the output shown in the editor console window.
``console.log`` and ``console.warn`` are used for the output and error streams respectively. This
behavior can be customized by setting your own functions to handle messages.
Use the :js:meth:`engine.setStdoutFunc` method to set a callback function for the output stream. Default
behavior is similar to this:
Use the :js:attr:`onPrint` override option to set a callback function for the output stream,
and the :js:attr:`onPrintError` override option to set a callback function for the error stream.
.. code-block:: js
function printStdout(text) {
function print(text) {
console.log(text);
}
engine.setStdoutFunc(printStdout);
Use the :js:meth:`engine.setStderrFunc` method to set a callback function for the error stream. Default
behavior is similar to this:
.. code-block:: js
function printStderr(text) {
console.warn("Error: " + text);
function printError(text) {
console.warn(text);
}
engine.setStderrFunc(printStderr);
engine.startGame({ onPrint: print, onPrintError: printError });
When handling the engine output keep in mind, that it may not be desirable to print it out in the
finished product. To control whether or not the current execution is actually a debug build you can
use ``$GODOT_DEBUG_ENABLED`` placeholder.
Further debugging options and a low level access to the execution environment are available in a form
of Emscripten's ``Module`` object. It can be accessed using the :js:attr:`engine.rtenv` property on the
engine instance.
finished product.