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 platform docs

Browse Source
This commit is contained in:
Leon Krause
2019-01-23 20:41:48 +01:00
parent 82ffb39992
commit 4cb5df447b
6 changed files with 458 additions and 301 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
development/compiling/compiling_for_web.rst
View File

@@ -10,7 +10,7 @@ Requirements
To compile export templates for the Web, the following is required:
- `Emscripten 1.37.9+ <http://kripken.github.io/emscripten-site>`__: If the version available
- `Emscripten 1.38.22+ <http://kripken.github.io/emscripten-site>`__: 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/getting_started/downloads.html>`__
- `Python 2.7+ or Python 3.5+ <https://www.python.org/>`__
@@ -29,6 +29,11 @@ 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 ``/``.
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::
@@ -66,18 +71,13 @@ asm.js, a highly optimizable subset of JavaScript, using Emscripten's
tool called ``asm2wasm``. Emscripten automatically takes care of both
processes, we simply run SCons.
The other method uses LLVM's WebAssembly backend. This backend is not yet
available in release versions of LLVM, only in development builds built with
``LLVM_EXPERIMENTAL_TARGETS_TO_BUILD=WebAssembly``.
Compiling with this backend outputs files in LLVM's ``.s`` format, which is
translated into actual WebAssembly using a tool called ``s2wasm``.
Emscripten manages these processes as well, so we just invoke SCons.
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.
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
``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 ``/``.
the LLVM's WebAssembly backend is used.

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

@@ -1,238 +0,0 @@
.. _doc_customizing_html5_shell:
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 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
`/misc/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
------------------------
When exporting the game, several placeholders in the HTML page are replaced
with values depending on the export:
+------------------------------+-----------------------------------------------+
| Placeholder | substituted by |
+==============================+===============================================+
| ``$GODOT_BASENAME`` | Basename of exported files without suffixes, |
| | e.g. ``game`` when exporting ``game.html`` |
+------------------------------+-----------------------------------------------+
| ``$GODOT_DEBUG_ENABLED`` | ``true`` if debugging, ``false`` otherwise |
+------------------------------+-----------------------------------------------+
| ``$GODOT_HEAD_INCLUDE`` | Custom string to include just before the end |
| | of the HTML ``<head>`` element |
+------------------------------+-----------------------------------------------+
The HTML file must evaluate the JavaScript file ``$GODOT_BASENAME.js``. This
file defines a global ``Engine`` object used to start the engine, :ref:`see
below <doc_javascript_engine_object>` for details.
The boot splash image is exported as ``$GODOT_BASENAME.png`` and can be used
e.g. in ``<img />`` elements.
``$GODOT_DEBUG_ENABLED`` can be useful to optionally display e.g. an output
console or other debug tools.
``$GODOT_HEAD_INCLUDE`` is replaced with the string specified by the export
option ``Html/Head Include``.
.. _doc_javascript_engine_object:
The ``Engine`` object
---------------------
The JavaScript global object ``Engine`` is defined by ``$GODOT_BASENAME.js``
and serves as an interface to the engine start-up process.
The object itself has only two methods, ``load()`` and ``unload()``.
``Engine.load(basePath)``
~~~~~~~~~~~~~~~~~~~~~~~~~
Loads the engine from the passed base path.
Returns a promise that resolves once the engine is loaded.
``Engine.unload()``
~~~~~~~~~~~~~~~~~~~
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
-------------------------------
The more interesting interface is accessed by instantiating ``Engine`` using
the ``new`` operator:
.. code-block:: js
var engine = new Engine();
This ``Engine`` instance, referred to as ``engine`` with a lower-case ``e``
from here, is a startable instance of the engine, usually a game. To start such
an instance, the global ``Engine`` object must be loaded, then the ``engine``
instance must be initialized and started.
``engine.init(basePath)``
~~~~~~~~~~~~~~~~~~~~~~~~~
Initializes the instance. If the engine wasn't loaded yet, a base path
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, 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. If ``file`` is
an ``ArrayBuffer`` or a view on one, the buffer will used as the 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.
``engine.start(arg1, arg2, …)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Starts the instance of the engine, handing the passed strings as arguments
to the ``main()`` function. This allows great control over how the engine
is used, but usually the other methods whose names start with ``engine.start``
are simpler to use.
Returns a promise that resolves once the engine started.
``engine.startGame(mainPack)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Starts the game with the main pack loaded from the passed URL string and
starts the engine with it.
If the engine isn't loaded yet, the base path of the passed URL will be
used to load the engine.
Returns a promise that resolves once the game started.
Configuring start-up behaviour
------------------------------
Beside starting the engine, other methods of the engine instance allow
configuring the behavior:
``engine.setUnloadAfterInit(enabled)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets whether the Engine will be unloaded automatically after the instance
is initialized. This frees browser memory by unloading files that are no
longer needed once the instance is initialized. However, if more instances of
the engine will be started, the Engine will have to be loaded again.
Defaults to ``true``.
``engine.setCanvas(canvasElem)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By default, the first canvas element on the page is used for rendering.
By calling this method, another canvas can be specified.
``engine.setCanvasResizedOnStart(enabled)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets whether the canvas will be resized to the width and height specified
in the project settings on start. Defaults to ``true``.
``engine.setLocale(locale)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By default, the engine will try to guess the locale to use from the
JavaScript environment. It is usually preferable to use a server-side
user-specified locale, or at least use the locale requested in the HTTP
``Accept-Language`` header. This method allows specifying such a custom locale
string.
``engine.setExecutableName(execName)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By default, the base name of the loaded engine files is used for the
executable name. This method allows specifying another name.
Customizing the presentation
----------------------------
The following methods are used to implement the presentation:
``engine.setProgressFunc(func)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This method is used to display download progress. The passed callback
function is called with two number arguments, the first argument specifies
bytes loaded so far, the second argument specifies the total number of bytes
to load.
.. code-block:: js
function printProgress(current, total) {
console.log("Loaded " + current + " of " + total + " bytes");
}
engine.setProgressFunc(printProgress);
If the total is 0, it couldn't be calculated. Possible reasons
include:
- Files are delivered with server-side chunked compression
- Files are delivered with server-side compression on Chromium
- Not all file downloads have started yet (usually on servers without multi-threading)
``engine.setStdoutFunc(func)``, ``engine.setStderrFunc(func)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These methods allow implementing custom behavior for the ``stdout`` and
``stderr`` streams. The functions passed in will be called with one string
argument specifying the string to print.
.. code-block:: js
function printStderr(text) {
console.warn("Error: " + text);
}
engine.setStderrFunc(printStderr);
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 respectively.
Accessing the Emscripten ``Module``
-----------------------------------
If you know what you're doing, you can access the runtime environment
(Emscripten's ``Module``) as ``engine.rtenv``. Check the official Emscripten
documentation for information on how to use it:
https://kripken.github.io/emscripten-site/docs/api_reference/module.html

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

@@ -4,12 +4,40 @@ Exporting for the Web
=====================
HTML5 export allows publishing games made in Godot Engine to the browser.
This requires support for the recent technologies `WebAssembly
<https://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.
This requires support for `WebAssembly
<https://webassembly.org/>`__ and `WebGL <https://www.khronos.org/webgl/>`__
in the user's browser.
.. Important::
Use the browser-integrated developer console, usually opened with :kbd:`F12`,
to view **debug information** like JavaScript, engine, and WebGL errors.
.. Attention::
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.
.. Tip::
Python offers an easy method to start a local server. Use
``python -m SimpleHTTPServer`` with Python 2 or ``python -m http.server`` with
Python 3 to serve the current working directory at ``http://localhost:8000``.
WebGL 2
-------
Until the *OpenGL ES 3* renderer is removed from Godot in favor of *Vulkan*,
HTML5 export uses *WebGL 2* when the *GLES3* option selected.
.. Warning::
Usage of WebGL 2 is not recommended due to its expected removal from Godot
without replacement.
WebGL 2 is not supported in all browsers. **Firefox** and
**Chromium** (Chrome, Opera) are the most popular supported browsers,
**Safari** and **Edge** do not work. On **iOS**, all browsers are based on
WebKit (i.e. Safari), so they will also not work.
Godot's WebGL 2 renderer has issues with 3D and is no longer maintained.
Limitations
-----------
@@ -18,13 +46,6 @@ 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.
Exported ``.html`` file must not be reused
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
On export, several text placeholders are replaced in the **generated HTML
file** specifically for the given export options. It must not be reused in
further exports.
Using cookies for data persistence
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -40,26 +61,51 @@ cases.
Full screen and mouse capture
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 such as ``_input`` or
``_unhandled_input``.
Browsers do not allow arbitrarily **entering full screen**. The same goes for
**capturing the cursor**. Instead, these actions have to occur as a response to
a JavaScript input event. In Godot, this means entering full screen from within
a pressed input event callback such as ``_input`` or ``_unhandled_input``.
Querying the :ref:`class_Input` singleton is not sufficient, the relevant
input event must currently be active.
For the same reason, the full screen project setting is ignored.
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>`.
HTTPClient
~~~~~~~~~~
Audio autoplay
~~~~~~~~~~~~~~
The ``HTTPClient`` implementation for the HTML5 platform has several
restrictions:
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.
.. 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`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The HTTP classes have several restrictions on the HTML5 platform:
- Accessing or changing the ``StreamPeer`` is not possible
- Blocking mode is not available
- Threaded/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>`_
- Subject to `same-origin policy <https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy>`__
Exported ``.html`` file must not be reused
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
On export, several text placeholders are replaced in the **generated HTML
file** specifically for the given export options. It must not be reused in
further exports.
Boot splash is not displayed
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The default HTML page does not display the boot splash while loading. However,
the image is exported as a PNG file, so :ref:`custom HTML pages <doc_customizing_html5_shell>`
can display it.
Unimplemented functionality
~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -68,23 +114,14 @@ The following functionality is currently unavailable on the HTML5 platform:
- Threads
- GDNative
- C#
- Clipboard synchronisation between engine and operating system
- Networking other than ``HTTPClient``
- Networking other than :ref:`class_HTTPClient` and :ref:`class_WebSocketClient`
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 functionality you're interested in has an issue yet. If not, open one
to communicate your interest.
Starting exported games from the local file system
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
working directory on ``http://localhost:8000``.
.. 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 functionality you're interested in has an issue yet. If not, open
one to communicate your interest.
Serving the files
-----------------
@@ -97,8 +134,7 @@ The generated ``.html`` file can be used as ``DirectoryIndex`` in Apache
servers and can be renamed to e.g. ``index.html`` at any time, its name is
never depended on by default.
The HTML page is designed to fit the game perfectly without cutting off
parts of the canvas when the browser window is scaled to the game's dimensions.
The HTML page draws the game at maximum size within the browser window.
This way it can be inserted into an ``<iframe>`` with the game's size, as is
common on most web game hosting sites.
@@ -111,8 +147,12 @@ the default HTML page, but is included for
:ref:`custom HTML pages <doc_customizing_html5_shell>`.
The ``.pck`` file is binary, usually delivered with the MIME-type
``application/octet-stream``. The ``.wasm`` file is delivered as
``application/wasm``.
:mimetype:`application/octet-stream`. The ``.wasm`` file is delivered as
:mimetype:`application/wasm`.
.. Caution::
Delivering the WebAssembly module (``.wasm``) with a MIME-type other than
:mimetype:`application/wasm` can prevent some start-up optimizations.
Delivering the files with server-side compression is recommended especially for
the ``.pck`` and ``.wasm`` files, which are usually large in size.
@@ -133,18 +173,12 @@ the default HTML page. See :ref:`doc_customizing_html5_shell`.
HTML page. This allows to, for example, load webfonts and third-party
JavaScript APIs, include CSS, or run JavaScript code.
Turning on **Export with Debug** when exporting will, in addition to enabling
various debug features of the engine, display a debug output below the canvas
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
------------------------------
In web builds, the ``JavaScript`` singleton is implemented. If offers a single
In web builds, the ``JavaScript`` singleton is implemented. It offers a single
method called ``eval`` that works similarly to the JavaScript function of the
same name. It takes a string as an argument and executes it as JavaScript code.
This allows interacting with the browser in ways not possible with script
@@ -179,10 +213,16 @@ also return ``null``. The availability of the singleton can be checked with the
func my_func3():
if OS.has_feature('JavaScript'):
JavaScript.eval("console.log('The JavaScript singleton is available')")
JavaScript.eval("""
console.log('The JavaScript singleton is available')
""")
else:
print("The JavaScript singleton is NOT available")
.. Tip::
GDScript's multi-line strings, surrounded by 3 quotes ``"""`` as in
``my_func3()`` above, are useful to keep JavaScript code readable.
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::

1
getting_started/workflow/export/index.rst
View File

@@ -14,6 +14,5 @@ Export
exporting_for_uwp
exporting_for_android
exporting_for_web
customizing_html5_shell
one-click_deploy
changing_application_icon_for_windows

355
tutorials/platform/customizing_html5_shell.rst Normal file
View File

@@ -0,0 +1,355 @@
.. _doc_customizing_html5_shell:
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 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
`/misc/dist/html/full-size.html <https://github.com/godotengine/godot/blob/master/misc/dist/html/full-size.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
- Adding a click-to-play button so games can be started in full-screen mode
- 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
Another sample HTML page is avilable at `/misc/dist/html/fixed-size.html <https://github.com/godotengine/godot/blob/master/misc/dist/html/fixed-size.html>`__.
This page uses a fixed size canvas with an output widget below. However, the
F12 browser console should be preferred as it can display additional
information, such as WebGL errors.
Placeholder substitution
------------------------
When exporting the game, several placeholders in the HTML page are replaced
with values depending on the export:
+------------------------------+-----------------------------------------------+
| Placeholder | substituted by |
+==============================+===============================================+
| ``$GODOT_BASENAME`` | Basename of exported files without suffixes, |
| | e.g. ``game`` when exporting ``game.html`` |
+------------------------------+-----------------------------------------------+
| ``$GODOT_DEBUG_ENABLED`` | ``true`` if debugging, ``false`` otherwise |
+------------------------------+-----------------------------------------------+
| ``$GODOT_HEAD_INCLUDE`` | Custom string to include just before the end |
| | of the HTML ``<head>`` element |
+------------------------------+-----------------------------------------------+
The HTML file must evaluate the JavaScript file ``$GODOT_BASENAME.js``. This
file defines a global ``Engine`` object used to start the engine, :ref:`see
below <doc_javascript_engine_object>` for details.
The boot splash image is exported as ``$GODOT_BASENAME.png`` and can be used
e.g. in ``<img />`` elements.
``$GODOT_DEBUG_ENABLED`` can be useful to optionally display e.g. an output
console or other debug tools.
``$GODOT_HEAD_INCLUDE`` is replaced with the string specified by the export
option ``Html/Head Include``.
.. _doc_javascript_engine_object:
The ``Engine`` object
---------------------
The JavaScript global object ``Engine`` is defined by ``$GODOT_BASENAME.js``
and serves as an interface to the engine start-up process.
The API is based on and requires basic understanding of `Promises <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises>`__.
The object itself has only the following methods:
.. js:function:: Engine.load(basePath)
Load the engine from the passed base path.
:param string basePath: Base path of the engine to load.
:returns: Promise which resolves once the engine is loaded.
.. js:function:: Engine.unload()
Unload the engine to free memory.
This is called automatically once the engine is started unless
explicitly disabled using :js:func:`engine.setUnloadAfterInit`.
.. js:function:: Engine.isWebGLAvailable([majorVersion = 1])
Check whether WebGL is available.
:param number majorVersion:
The major WebGL version to check for. Defaults to 1 for *WebGL 1.0*.
:returns:
``true`` if the given major version of WebGL is available, ``false``
otherwise.
.. js:function:: Engine.setWebAssemblyFilenameExtension(extension)
When loading the engine, the filename extension of the WebAssembly module
is assumed to be ``wasm``. This function allows usage of an alternate
extension.
.. code-block:: js
Engine.setWebAssemblyFilenameExtension('dat');
// Load 'mygame.dat' as WebAssembly module.
Engine.load('mygame');
This is useful for outdated hosts that only accept uploads of files with
certain filename extensions.
:param string extension:
Filename extension without preceding dot.
.. Note::
Depending on the host, using an alternate filename extension can prevent
some start-up optimizations. This occurs when the file is delivered with a
MIME-type other than :mimetype:`application/wasm`.
Starting an ``Engine`` instance
-------------------------------
:js:class:`Engine` also acts a class:
.. js:class:: Engine
An instance of the engine that can be started, usually a game.
Instantiate the class using the ``new`` operator:
.. code-block:: js
var engine = new Engine();
This yields an :js:class:`Engine` instance, referred to as ``engine`` with a
lower-case ``e`` from here.
To start such an instance, the global ``Engine`` object must be loaded,
then the ``engine`` instance must be initialized and finally started.
.. js:function:: engine.init([basePath])
Initialize the instance. The instance can then be started with one of the
``start`` functions, usually :js:func:`engine.startGame`.
:param string basePath:
The base path to the engine, same as in :js:func:`Engine.load`.
Must be passed only if the engine hasn't been loaded yet.
:returns: Promise that resolves once the engine is loaded and initialized.
.. js:function:: engine.preloadFile(file[, path])
Load a file so it is available in the file system once the instance runs. Must
be called **before** starting the instance.
:param file:
If type is string, the file will be loaded from that path.
If type is ``ArrayBuffer`` or a view on one, the buffer will used as
the content of the file.
:param string path:
Path by which the file will be available. Mandatory if ``file`` is not
a string. If not passed, the path is derived from the URL of the loaded
file.
:returns: Promise that resolves once the file is preloaded.
.. js:function:: engine.start([arg1, arg2, …])
Starts the instance of the engine, using the passed strings as
command line arguments. This allows great control over how the engine is
started, but usually the other methods starting with ``engine.start`` are
simpler and should be used instead.
If the instance has not yet been initialized with :js:func:`engine.init`,
it will be.
The engine must be loaded beforehand.
Requires that the engine has been loaded, and that a canvas can be found on
the page.
:param string variadic: Command line arguments.
:returns: Promise that resolves once the engine started.
.. js:function:: engine.startGame(mainPack)
Initializes the engine if not yet initialized and starts the game with the
main pack loaded from the passed URL.
If the engine isn't loaded yet, the base path of the passed URL will be
used to load the engine.
This function ignores overrides of filenames and their extensions to start
only the main pack passed as argument.
:param string mainPack:
Path to the main pack to start. Also used as base path to load the
engine if not loaded already.
:returns: Promise that resolves once the game started.
Configuring start-up behaviour
------------------------------
Beside starting the engine, other methods of the engine instance allow
configuring the behavior:
.. js:function:: engine.setUnloadAfterInit(enabled)
Specify whether the Engine will be unloaded automatically after the
instance is initialized.
This frees browser memory by unloading files that are no longer needed once
the instance is initialized. However, if more instances of the engine will
be started, the Engine will have to be loaded again.
Enabled by default.
:param boolean enabled:
``true`` if the engine shall be unloaded after initializing,
``false`` otherwise.
.. js:function:: engine.setCanvas(canvasElem)
Specify a canvas to use.
By default, the first canvas element on the page is used for rendering.
:param HTMLCanvasElement canvasElem: The canvas to use.
.. js:function:: engine.setCanvasResizedOnStart(enabled)
Specifies whether the canvas will be resized to the width and height
specified in the project settings on start.
Enabled by default.
:param boolean enabled:
``true`` if the canvas shall be resized on start, ``false`` otherwise.
.. js:function:: engine.setLocale(locale)
By default, the engine will try to guess the locale to use from the
JavaScript environment. It is usually preferable to use a server-side
user-specified locale, or at least use the locale requested in the HTTP
``Accept-Language`` header. This method allows specifying such a custom
locale string.
For example, with PHP:
.. code-block:: php
engine.setLocale(<?php echo Locale::acceptFromHttp($_SERVER['HTTP_ACCEPT_LANGUAGE']); ?>);
:param string locale:
Locale.
.. seealso:: List of :ref:`locales <doc_locales>`.
.. js:function:: engine.setExecutableName(execName)
Specify the virtual filename of the executable.
A real executable file doesn't exist for the HTML5 platform. However,
a virtual filename is stored by the engine for compatibility with other
platforms.
By default, the base name of the loaded engine files is used.
This method allows specifying another name.
This affects the output of :ref:`OS.get_executable_path() <class_OS_method_get_executable_path>`
and the automatically started main pack, :file:`{ExecutableName}.pck`.
:param string execName: Executable name.
Customizing the presentation
----------------------------
The following methods are used to implement the presentation:
.. js:function:: engine.setProgressFunc(callback)
Set the callback for displaying download progress.
:param function callback:
Callback called once per frame with two number arguments:
bytes loaded so far, and total bytes to load.
.. code-block:: js
function printProgress(current, total) {
console.log("Loaded " + current + " of " + total + " bytes");
}
engine.setProgressFunc(printProgress);
If the total is 0, it couldn't be calculated. Possible reasons
include:
- Files are delivered with server-side chunked compression
- Files are delivered with server-side compression on Chromium
- Not all file downloads have started yet (usually on servers without
multi-threading)
.. Note::
For ease of use, the callback is only called once per frame, so that usage
of ``requestAnimationFrame()`` is not necessary.
.. js:function:: engine.setStdoutFunc(callback)
Specify the standard output stream callback.
:param function callback:
Callback function called with one argument, the string to print.
.. code-block:: js
function printStdout(text) {
console.log(text);
}
engine.setStdoutFunc(printStdout);
This method should usually only be used in debug pages. The
``$GODOT_DEBUG_ENABLED`` placeholder can be used to check for this.
By default, ``console.log()`` is used.
.. js:function:: engine.setStderrFunc(callback)
Specify the standard error stream callback.
:param function callback:
Callback function called with one argument, the string to print.
.. code-block:: js
function printStderr(text) {
console.warn("Error: " + text);
}
engine.setStderrFunc(printStderr);
This method should usually only be used in debug pages. The
``$GODOT_DEBUG_ENABLED`` placeholder can be used to check for this.
By default, ``console.warn()`` is used.
Accessing the Emscripten ``Module``
-----------------------------------
If you know what you're doing, you can access the runtime environment
(Emscripten's ``Module``) as ``engine.rtenv``. Check the official Emscripten
documentation for information on how to use it:
https://kripken.github.io/emscripten-site/docs/api_reference/module.html

1
tutorials/platform/index.rst
View File

@@ -7,4 +7,5 @@ Platform-specific
android_in_app_purchases
services_for_ios
customizing_html5_shell
consoles