mirror of
https://github.com/godotengine/godot-docs.git
synced 2025-12-31 17:49:03 +03:00
267 lines
12 KiB
ReStructuredText
267 lines
12 KiB
ReStructuredText
.. _doc_html5_shell_classref:
|
|
|
|
HTML5 shell class reference
|
|
===========================
|
|
|
|
Projects exported for the Web expose the ``Engine`` class to the JavaScript environment, that allows
|
|
fine control over the engine's start-up process.
|
|
|
|
This API is built in an asynchronous manner and requires basic understanding
|
|
of `Promises <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises>`__.
|
|
|
|
Engine
|
|
------
|
|
|
|
The ``Engine`` class provides methods for loading and starting exported projects on the Web. For default export
|
|
settings, this is already part of the exported HTML page. To understand practical use of the ``Engine`` class,
|
|
see :ref:`Custom HTML page for Web export <doc_customizing_html5_shell>`.
|
|
|
|
Static Methods
|
|
^^^^^^^^^^^^^^
|
|
|
|
+---------+-------------------------------------------------------------------------------------------------------------------+
|
|
| Promise | `Engine.load <#Engine.load>`__ **(** string basePath **)** |
|
|
+---------+-------------------------------------------------------------------------------------------------------------------+
|
|
| void | `Engine.unload <#Engine.unload>`__ **(** **)** |
|
|
+---------+-------------------------------------------------------------------------------------------------------------------+
|
|
| boolean | `Engine.isWebGLAvailable <#Engine.isWebGLAvailable>`__ **(** *[ number majorVersion=1 ]* **)** |
|
|
+---------+-------------------------------------------------------------------------------------------------------------------+
|
|
| void | `Engine.setWebAssemblyFilenameExtension <#Engine.setWebAssemblyFilenameExtension>`__ **(** string extension **)** |
|
|
+---------+-------------------------------------------------------------------------------------------------------------------+
|
|
|
|
Instance Properties
|
|
^^^^^^^^^^^^^^^^^^^
|
|
|
|
+-----------------------+----------------------------------+
|
|
| Emscripten ``Module`` | `engine.rtenv <#engine.rtenv>`__ |
|
|
+-----------------------+----------------------------------+
|
|
|
|
Instance Methods
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
+---------+------------------------------------------------------------------------------------------------------+
|
|
| Engine | `Engine <#Engine>`__ **(** **)** |
|
|
+---------+------------------------------------------------------------------------------------------------------+
|
|
| Promise | `engine.init <#engine.init>`__ **(** *[ string basePath ]* **)** |
|
|
+---------+------------------------------------------------------------------------------------------------------+
|
|
| Promise | `engine.preloadFile <#engine.preloadFile>`__ **(** string\|ArrayBuffer file *[, string path ]* **)** |
|
|
+---------+------------------------------------------------------------------------------------------------------+
|
|
| Promise | `engine.start <#engine.start>`__ **(** *[ string arg1, string arg2, … ]* **)** |
|
|
+---------+------------------------------------------------------------------------------------------------------+
|
|
| Promise | `engine.startGame <#engine.startGame>`__ **(** string execName, string mainPack **)** |
|
|
+---------+------------------------------------------------------------------------------------------------------+
|
|
| void | `engine.setUnloadAfterInit <#engine.setUnloadAfterInit>`__ **(** boolean enabled **)** |
|
|
+---------+------------------------------------------------------------------------------------------------------+
|
|
| void | `engine.setCanvas <#engine.setCanvas>`__ **(** HTMLCanvasElement canvasElem **)** |
|
|
+---------+------------------------------------------------------------------------------------------------------+
|
|
| void | `engine.setCanvasResizedOnStart <#engine.setCanvasResizedOnStart>`__ **(** boolean enabled **)** |
|
|
+---------+------------------------------------------------------------------------------------------------------+
|
|
| void | `engine.setLocale <#engine.setLocale>`__ **(** string locale **)** |
|
|
+---------+------------------------------------------------------------------------------------------------------+
|
|
| void | `engine.setExecutableName <#engine.setExecutableName>`__ **(** string execName **)** |
|
|
+---------+------------------------------------------------------------------------------------------------------+
|
|
| void | `engine.setProgressFunc <#engine.setProgressFunc>`__ **(** function callback **)** |
|
|
+---------+------------------------------------------------------------------------------------------------------+
|
|
| void | `engine.setStdoutFunc <#engine.setStdoutFunc>`__ **(** function callback **)** |
|
|
+---------+------------------------------------------------------------------------------------------------------+
|
|
| void | `engine.setStderrFunc <#engine.setStderrFunc>`__ **(** function callback **)** |
|
|
+---------+------------------------------------------------------------------------------------------------------+
|
|
|
|
|
|
Static Method Descriptions
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
.. js:method:: Engine.load(basePath)
|
|
|
|
Load the engine from the specified base path.
|
|
|
|
:param string basePath:
|
|
Base path of the engine to load.
|
|
:returns:
|
|
Promise which resolves once the engine is loaded.
|
|
|
|
.. js:method:: Engine.unload()
|
|
|
|
Unload the engine to free memory.
|
|
|
|
This method is called automatically once the engine is started unless
|
|
explicitly disabled using :js:meth:`engine.setUnloadAfterInit`.
|
|
|
|
.. js:method:: Engine.isWebGLAvailable([majorVersion = 1])
|
|
|
|
Check whether WebGL is available. Optionally, specify a particular version of WebGL to check for.
|
|
|
|
: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:method:: Engine.setWebAssemblyFilenameExtension(extension)
|
|
|
|
Set an alternative filename extension for the WebAssembly module. By default
|
|
it is assumed to be ``wasm``.
|
|
|
|
:param string extension:
|
|
Filename extension without preceding dot.
|
|
|
|
|
|
Instance Property Descriptions
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
.. js:attribute:: engine.rtenv
|
|
|
|
The runtime environment provided by Emscripten's ``Module``. For more information
|
|
refer to the `official documentation <https://emscripten.org/docs/api_reference/module.html>`__ on Emscripten.
|
|
|
|
Instance Method Descriptions
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
.. js:class:: Engine
|
|
|
|
Create a new instance of the ``Engine`` class.
|
|
|
|
.. js:method:: engine.init([basePath])
|
|
|
|
Initialize the engine instance. Optionally, pass the base path to the engine to load it,
|
|
if it hasn't been loaded yet. See :js:meth:`Engine.load`.
|
|
|
|
:param string basePath:
|
|
Base path of the engine to load.
|
|
|
|
:returns:
|
|
Promise that resolves once the engine is loaded and initialized.
|
|
|
|
.. js:method:: engine.preloadFile(file[, path])
|
|
|
|
Load a file so it is available in the instance's file system once it runs. Must
|
|
be called **before** starting the instance.
|
|
|
|
:param string|ArrayBuffer 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 accessible. Required, 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 loaded.
|
|
|
|
.. js:method:: engine.start([arg1, arg2, …])
|
|
|
|
Start the instance of the engine, using the passed strings as
|
|
command line arguments. :js:meth:`engine.startGame` can be used
|
|
in typical cases instead.
|
|
|
|
This will initialize the instance if it is not initialized. For manual
|
|
initialization, see :js:meth:`engine.init`. The engine must be loaded beforehand.
|
|
|
|
Fails if a canvas cannot be found on the page.
|
|
|
|
:param string variadic:
|
|
Command line argument.
|
|
|
|
:returns:
|
|
Promise that resolves once the engine started.
|
|
|
|
.. js:method:: engine.startGame(execName, mainPack)
|
|
|
|
Start the game instance using the given executable URL and main pack URL.
|
|
|
|
This will initialize the instance if it is not initialized. For manual
|
|
initialization, see :js:meth:`engine.init`.
|
|
|
|
This will load the engine if it is not loaded. The base path of the
|
|
executable URL will be used as the engine base path.
|
|
|
|
:param string execName:
|
|
Executable name in a form of URL, omitting filename extension.
|
|
|
|
:param string mainPack:
|
|
URL of the main pack to start the game.
|
|
|
|
:returns:
|
|
Promise that resolves once the game started.
|
|
|
|
.. js:method:: engine.setUnloadAfterInit(enabled)
|
|
|
|
Specify whether the engine will be unloaded automatically after the
|
|
instance is initialized. Enabled by default.
|
|
|
|
:param boolean enabled:
|
|
``true`` if the engine shall be unloaded after initializing,
|
|
``false`` otherwise.
|
|
|
|
.. js:method:: engine.setCanvas(canvasElem)
|
|
|
|
Specify a canvas HTML element to use. By default, the first canvas element
|
|
on the page is used for rendering.
|
|
|
|
:param HTMLCanvasElement canvasElem:
|
|
The canvas element to use.
|
|
|
|
.. js:method:: 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:method:: engine.setLocale(locale)
|
|
|
|
Specify a language code to select the proper localization for the game.
|
|
|
|
.. seealso:: Complete list of :ref:`supported locales <doc_locales>`.
|
|
|
|
:param string locale:
|
|
Language code.
|
|
|
|
.. js:method:: engine.setExecutableName(execName)
|
|
|
|
Specify the virtual filename of the executable. By default, the base name
|
|
of the loaded engine files is used.
|
|
|
|
This affects the output of :ref:`OS.get_executable_path() <class_OS_method_get_executable_path>`
|
|
and sets the automatically started main pack to :file:`{ExecutableName}.pck`.
|
|
|
|
:param string execName:
|
|
Executable name.
|
|
|
|
.. js:method:: engine.setProgressFunc(callback)
|
|
|
|
Specify a callback function for displaying download progress. The callback function is
|
|
called once per frame, so that the usage of ``requestAnimationFrame()`` is not necessary.
|
|
|
|
If the callback function receives a total amount of bytes as 0, this means that
|
|
it is impossible to calculate. 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)
|
|
|
|
:param function callback:
|
|
The callback function must accept two numeric arguments: the amount of bytes
|
|
loaded so far, and the total number of bytes to load.
|
|
|
|
.. js:method:: engine.setStdoutFunc(callback)
|
|
|
|
Specify a callback function for handling the standard output stream. This method
|
|
should usually only be used in debug pages. By default, ``console.log()`` is used.
|
|
|
|
:param function callback:
|
|
The callback function must accept one string argument: the message to print.
|
|
|
|
.. js:method:: engine.setStderrFunc(callback)
|
|
|
|
Specify a callback function for handling the standard error stream. This method
|
|
should usually only be used in debug pages. By default, ``console.warn()`` is used.
|
|
|
|
:param function callback:
|
|
The callback function must accept one string argument: the message to print.
|