|
|
@@ -1,355 +1,201 @@
|
|
|
.. _doc_customizing_html5_shell:
|
|
|
|
|
|
-Customizing the Web export HTML page
|
|
|
+Custom HTML page for Web export
|
|
|
====================================
|
|
|
|
|
|
-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``.
|
|
|
+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,
|
|
|
+such page allows to customize the initialization process for the engine.
|
|
|
|
|
|
-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 available 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*.
|
|
|
+Some use-cases where customizing the default page is useful include:
|
|
|
|
|
|
- :returns:
|
|
|
- ``true`` if the given major version of WebGL is available, ``false``
|
|
|
- otherwise.
|
|
|
+- Loading files from a different directory than the page;
|
|
|
+- Loading a ``.zip`` file instead of a ``.pck`` file as the main pack;
|
|
|
+- Loading the engine from a different directory than the main pack file;
|
|
|
+- Adding a click-to-play button so that games can be started in the fullscreen mode;
|
|
|
+- Loading some extra files before the engine starts, making them available in
|
|
|
+ the project file system as soon as possible;
|
|
|
+- Passing custom command line arguments, e.g. ``-s`` to start a ``MainLoop`` script.
|
|
|
|
|
|
-.. 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:
|
|
|
+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.
|
|
|
+
|
|
|
+.. 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.
|
|
|
+
|
|
|
+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.
|
|
|
+
|
|
|
+.. image:: img/html5_export_options.png
|
|
|
+
|
|
|
+- ``$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_HEAD_INCLUDE``:
|
|
|
+ A custom string to include in the HTML document just before the end of the ``<head>`` tag. It
|
|
|
+ is customized in the export options under the *Html / Head Include* section. While you fully
|
|
|
+ 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.
|
|
|
+
|
|
|
+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.
|
|
|
+
|
|
|
+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.
|
|
|
|
|
|
.. 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.
|
|
|
+ const execName = "path://to/executable"
|
|
|
+ const mainPack = "path://to/main_pack"
|
|
|
|
|
|
- :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.
|
|
|
+ const engine = new Engine();
|
|
|
+ engine.startGame(execName, mainPack)
|
|
|
|
|
|
- :returns: Promise that resolves once the file is preloaded.
|
|
|
+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`
|
|
|
+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.
|
|
|
|
|
|
-.. js:function:: engine.start([arg1, arg2, …])
|
|
|
+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.
|
|
|
|
|
|
- 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.
|
|
|
+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.
|
|
|
|
|
|
- If the instance has not yet been initialized with :js:func:`engine.init`,
|
|
|
- it will be.
|
|
|
+.. 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.
|
|
|
|
|
|
- The engine must be loaded beforehand.
|
|
|
+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.
|
|
|
|
|
|
- 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(execName, mainPack)
|
|
|
-
|
|
|
- Initializes the engine if not yet initialized, loads the executable,
|
|
|
- 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 executable name
|
|
|
- will be used to load the engine.
|
|
|
-
|
|
|
- :param string execName:
|
|
|
- Executable's name (URL) to start. Also used as base path to load the
|
|
|
- engine if not loaded already. Should not contain the file's extension.
|
|
|
-
|
|
|
- :param string mainPack:
|
|
|
- Path (URL) to the main pack to start.
|
|
|
-
|
|
|
- :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>`.
|
|
|
+.. code-block:: js
|
|
|
|
|
|
-.. js:function:: engine.setExecutableName(execName)
|
|
|
+ Engine.setWebAssemblyFilenameExtension("dat");
|
|
|
+ // Load mygame.dat as WebAssembly module.
|
|
|
+ Engine.load("mygame");
|
|
|
|
|
|
- Specify the virtual filename of the executable.
|
|
|
+.. 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.
|
|
|
|
|
|
- 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.
|
|
|
+Customizing the behavior
|
|
|
+------------------------
|
|
|
+In the Web environment several methods can be used to guarantee that the game will work as intended.
|
|
|
|
|
|
- By default, the base name of the loaded engine files is used.
|
|
|
- This method allows specifying another name.
|
|
|
+If you target a specific version of WebGL, or just want to check if WebGL is available at all,
|
|
|
+you can call the :js:meth:`Engine.isWebGLAvailable` method. It optionally takes an argument that
|
|
|
+allows to test for a specific major version of WebGL.
|
|
|
|
|
|
- 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`.
|
|
|
+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.
|
|
|
|
|
|
- :param string execName: Executable name.
|
|
|
+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.
|
|
|
|
|
|
Customizing the presentation
|
|
|
----------------------------
|
|
|
+Several methods can be used to further customize the look and behavior of the game on your page.
|
|
|
|
|
|
-The following methods are used to implement the presentation:
|
|
|
-
|
|
|
-.. js:function:: engine.setProgressFunc(callback)
|
|
|
+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 itself.
|
|
|
|
|
|
- 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.
|
|
|
+.. code-block:: js
|
|
|
|
|
|
-.. js:function:: engine.setStdoutFunc(callback)
|
|
|
+ const canvasElement = document.querySelector("#my-canvas-element");
|
|
|
+ engine.setCanvas(canvasElement);
|
|
|
|
|
|
- Specify the standard output stream callback.
|
|
|
+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.
|
|
|
|
|
|
- :param function callback:
|
|
|
- Callback function called with one argument, the string to print.
|
|
|
+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.
|
|
|
|
|
|
- .. code-block:: js
|
|
|
+.. code-block:: js
|
|
|
|
|
|
- function printStdout(text) {
|
|
|
- console.log(text);
|
|
|
- }
|
|
|
- engine.setStdoutFunc(printStdout);
|
|
|
+ function printProgress(current, total) {
|
|
|
+ console.log("Loaded " + current + " of " + total + " bytes");
|
|
|
+ }
|
|
|
+ engine.setProgressFunc(printProgress);
|
|
|
|
|
|
- This method should usually only be used in debug pages. The
|
|
|
- ``$GODOT_DEBUG_ENABLED`` placeholder can be used to check for this.
|
|
|
+Be aware that in some cases ``total`` can be ``0``. This means that it cannot be calculated.
|
|
|
|
|
|
- By default, ``console.log()`` is used.
|
|
|
+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
|
|
|
+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.
|
|
|
|
|
|
-.. js:function:: engine.setStderrFunc(callback)
|
|
|
+Debugging
|
|
|
+---------
|
|
|
+To debug exported projects, it may be useful to read the standard output and error streams generated
|
|
|
+by the engine. This is similar to the output shown in the editor console window. By default, standard
|
|
|
+``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.
|
|
|
|
|
|
- Specify the standard error stream callback.
|
|
|
+Use the :js:meth:`engine.setStdoutFunc` method to set a callback function for the output stream. Default
|
|
|
+behavior is similar to this:
|
|
|
|
|
|
- :param function callback:
|
|
|
- Callback function called with one argument, the string to print.
|
|
|
+.. code-block:: js
|
|
|
|
|
|
- .. code-block:: js
|
|
|
+ function printStdout(text) {
|
|
|
+ console.log(text);
|
|
|
+ }
|
|
|
+ engine.setStdoutFunc(printStdout);
|
|
|
|
|
|
- function printStderr(text) {
|
|
|
- console.warn("Error: " + text);
|
|
|
- }
|
|
|
- engine.setStderrFunc(printStderr);
|
|
|
+Use the :js:meth:`engine.setStderrFunc` method to set a callback function for the error stream. Default
|
|
|
+behavior is similar to this:
|
|
|
|
|
|
- This method should usually only be used in debug pages. The
|
|
|
- ``$GODOT_DEBUG_ENABLED`` placeholder can be used to check for this.
|
|
|
+.. code-block:: js
|
|
|
|
|
|
- By default, ``console.warn()`` is used.
|
|
|
+ function printStderr(text) {
|
|
|
+ console.warn("Error: " + text);
|
|
|
+ }
|
|
|
+ engine.setStderrFunc(printStderr);
|
|
|
|
|
|
-Accessing the Emscripten ``Module``
|
|
|
------------------------------------
|
|
|
+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.
|
|
|
|
|
|
-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
|
|
|
+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.
|
Yuri Sizov
