mirror of
https://github.com/stan220/godot-docs.git
synced 2026-09-08 18:29:11 +00:00
Merge pull request #4683 from Faless/js/doc
Update HTML5 classref with autogenerated jsdoc.
This commit is contained in:
Rémi Verschelde
@@ -3,7 +3,7 @@
|
||||
HTML5 shell class reference
|
||||
===========================
|
||||
|
||||
Projects exported for the Web expose the ``Engine`` class to the JavaScript environment, that allows
|
||||
Projects exported for the Web expose the :js:class:`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
|
||||
@@ -19,248 +19,334 @@ 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>`__ |
|
||||
+-----------------------+----------------------------------+
|
||||
+---------+-----------------------------------------------------------------------------------------------+
|
||||
| Promise | :js:attr:`load <Engine.load>` **(** string basePath **)** |
|
||||
+---------+-----------------------------------------------------------------------------------------------+
|
||||
| void | :js:attr:`unload <Engine.unload>` **(** **)** |
|
||||
+---------+-----------------------------------------------------------------------------------------------+
|
||||
| boolean | :js:attr:`isWebGLAvailable <Engine.isWebGLAvailable>` **(** *[ number majorVersion=1 ]* **)** |
|
||||
+---------+-----------------------------------------------------------------------------------------------+
|
||||
|
||||
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 **)** |
|
||||
+---------+------------------------------------------------------------------------------------------------------+
|
||||
+---------+---------------------------------------------------------------------------------------------------------------+
|
||||
| Promise | :js:attr:`init <Engine.prototype.init>` **(** *[ string basePath ]* **)** |
|
||||
+---------+---------------------------------------------------------------------------------------------------------------+
|
||||
| Promise | :js:attr:`preloadFile <Engine.prototype.preloadFile>` **(** string\|ArrayBuffer file *[, string path ]* **)** |
|
||||
+---------+---------------------------------------------------------------------------------------------------------------+
|
||||
| Promise | :js:attr:`start <Engine.prototype.start>` **(** EngineConfig override **)** |
|
||||
+---------+---------------------------------------------------------------------------------------------------------------+
|
||||
| Promise | :js:attr:`startGame <Engine.prototype.startGame>` **(** EngineConfig override **)** |
|
||||
+---------+---------------------------------------------------------------------------------------------------------------+
|
||||
| void | :js:attr:`copyToFS <Engine.prototype.copyToFS>` **(** string path, ArrayBuffer buffer **)** |
|
||||
+---------+---------------------------------------------------------------------------------------------------------------+
|
||||
| void | :js:attr:`requestQuit <Engine.prototype.requestQuit>` **(** **)** |
|
||||
+---------+---------------------------------------------------------------------------------------------------------------+
|
||||
|
||||
.. js:class:: Engine( initConfig )
|
||||
|
||||
Static Method Descriptions
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Create a new Engine instance with the given configuration.
|
||||
|
||||
.. js:method:: Engine.load(basePath)
|
||||
:param EngineConfig initConfig:
|
||||
The initial config for this instance.
|
||||
|
||||
Load the engine from the specified base path.
|
||||
**Static Methods**
|
||||
|
||||
:param string basePath:
|
||||
Base path of the engine to load.
|
||||
:returns:
|
||||
Promise which resolves once the engine is loaded.
|
||||
.. js:function:: load( basePath )
|
||||
|
||||
.. js:method:: Engine.unload()
|
||||
Load the engine from the specified base path.
|
||||
|
||||
Unload the engine to free memory.
|
||||
:param string basePath:
|
||||
Base path of the engine to load.
|
||||
|
||||
This method is called automatically once the engine is started unless
|
||||
explicitly disabled using :js:meth:`engine.setUnloadAfterInit`.
|
||||
:return:
|
||||
A Promise that resolves once the engine is loaded.
|
||||
|
||||
.. js:method:: Engine.isWebGLAvailable([majorVersion = 1])
|
||||
:rtype: Promise
|
||||
|
||||
Check whether WebGL is available. Optionally, specify a particular version of WebGL to check for.
|
||||
.. js:function:: unload( )
|
||||
|
||||
: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.
|
||||
Unload the engine to free memory.
|
||||
|
||||
.. js:method:: Engine.setWebAssemblyFilenameExtension(extension)
|
||||
This method will be called automatically depending on the configuration. See :js:attr:`unloadAfterInit`.
|
||||
|
||||
Set an alternative filename extension for the WebAssembly module. By default
|
||||
it is assumed to be ``wasm``.
|
||||
.. js:function:: isWebGLAvailable( [ majorVersion=1 ] )
|
||||
|
||||
:param string extension:
|
||||
Filename extension without preceding dot.
|
||||
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.
|
||||
|
||||
Instance Property Descriptions
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
:return:
|
||||
If the given major version of WebGL is available.
|
||||
|
||||
.. js:attribute:: engine.rtenv
|
||||
:rtype: boolean
|
||||
|
||||
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 Methods**
|
||||
|
||||
Instance Method Descriptions
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
.. js:function:: prototype.init( [ basePath ] )
|
||||
|
||||
.. js:class:: Engine
|
||||
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`.
|
||||
|
||||
Create a new instance of the ``Engine`` class.
|
||||
:param string basePath:
|
||||
Base path of the engine to load.
|
||||
|
||||
.. js:method:: engine.init([basePath])
|
||||
:return:
|
||||
A ``Promise`` that resolves once the engine is loaded and initialized.
|
||||
|
||||
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`.
|
||||
:rtype: Promise
|
||||
|
||||
:param string basePath:
|
||||
Base path of the engine to load.
|
||||
.. js:function:: prototype.preloadFile( file [, path ] )
|
||||
|
||||
:returns:
|
||||
Promise that resolves once the engine is loaded and initialized.
|
||||
Load a file so it is available in the instance's file system once it runs. Must be called **before** starting the
|
||||
instance.
|
||||
|
||||
.. js:method:: engine.preloadFile(file[, path])
|
||||
If not provided, the ``path`` is derived from the URL of the loaded file.
|
||||
|
||||
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:
|
||||
The file to preload.
|
||||
|
||||
:param string|ArrayBuffer file:
|
||||
If type is ``string``, the file will be loaded from that path.
|
||||
If a ``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.
|
||||
If an ``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.
|
||||
:param string path:
|
||||
Path by which the file will be accessible. Required, if ``file`` is not a string.
|
||||
|
||||
:returns:
|
||||
Promise that resolves once the file is loaded.
|
||||
:return:
|
||||
A Promise that resolves once the file is loaded.
|
||||
|
||||
.. js:method:: engine.start([arg1, arg2, …])
|
||||
:rtype: Promise
|
||||
|
||||
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.
|
||||
.. js:function:: prototype.start( override )
|
||||
|
||||
This will initialize the instance if it is not initialized. For manual
|
||||
initialization, see :js:meth:`engine.init`. The engine must be loaded beforehand.
|
||||
Start the engine instance using the given override configuration (if any).
|
||||
:js:meth:`startGame <Engine.prototype.startGame>` can be used in typical cases instead.
|
||||
|
||||
Fails if a canvas cannot be found on the page.
|
||||
This will initialize the instance if it is not initialized. For manual initialization, see :js:meth:`init <Engine.prototype.init>`.
|
||||
The engine must be loaded beforehand.
|
||||
|
||||
:param string variadic:
|
||||
Command line argument.
|
||||
Fails if a canvas cannot be found on the page, or not specified in the configuration.
|
||||
|
||||
:returns:
|
||||
Promise that resolves once the engine started.
|
||||
:param EngineConfig override:
|
||||
An optional configuration override.
|
||||
|
||||
.. js:method:: engine.startGame(execName, mainPack)
|
||||
:return:
|
||||
Promise that resolves once the engine started.
|
||||
|
||||
Start the game instance using the given executable URL and main pack URL.
|
||||
:rtype: Promise
|
||||
|
||||
This will initialize the instance if it is not initialized. For manual
|
||||
initialization, see :js:meth:`engine.init`.
|
||||
.. js:function:: prototype.startGame( override )
|
||||
|
||||
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.
|
||||
Start the game instance using the given configuration override (if any).
|
||||
|
||||
:param string execName:
|
||||
Executable name in a form of URL, omitting filename extension.
|
||||
This will initialize the instance if it is not initialized. For manual initialization, see :js:meth:`init <Engine.prototype.init>`.
|
||||
|
||||
:param string mainPack:
|
||||
URL of the main pack to start the game.
|
||||
This will load the engine if it is not loaded, and preload the main pck.
|
||||
|
||||
:returns:
|
||||
Promise that resolves once the game started.
|
||||
This method expects the initial config (or the override) to have both the :js:attr:`executable` and :js:attr:`mainPack`
|
||||
properties set (normally done by the editor during export).
|
||||
|
||||
.. js:method:: engine.setUnloadAfterInit(enabled)
|
||||
:param EngineConfig override:
|
||||
An optional configuration override.
|
||||
|
||||
Specify whether the engine will be unloaded automatically after the
|
||||
instance is initialized. Enabled by default.
|
||||
:return:
|
||||
Promise that resolves once the game started.
|
||||
|
||||
:param boolean enabled:
|
||||
``true`` if the engine shall be unloaded after initializing,
|
||||
``false`` otherwise.
|
||||
:rtype: Promise
|
||||
|
||||
.. js:method:: engine.setCanvas(canvasElem)
|
||||
.. js:function:: prototype.copyToFS( path, buffer )
|
||||
|
||||
Specify a canvas HTML element to use. By default, the first canvas element
|
||||
on the page is used for rendering.
|
||||
Create a file at the specified ``path`` with the passed as ``buffer`` in the instance's file system.
|
||||
|
||||
:param HTMLCanvasElement canvasElem:
|
||||
The canvas element to use.
|
||||
:param string path:
|
||||
The location where the file will be created.
|
||||
|
||||
.. js:method:: engine.setCanvasResizedOnStart(enabled)
|
||||
:param ArrayBuffer buffer:
|
||||
The content of the file.
|
||||
|
||||
Specifies whether the canvas will be resized to the width and height
|
||||
specified in the project settings on start. Enabled by default.
|
||||
.. js:function:: prototype.requestQuit( )
|
||||
|
||||
:param boolean enabled:
|
||||
``true`` if the canvas shall be resized on start, ``false`` otherwise.
|
||||
Request that the current instance quit.
|
||||
|
||||
.. js:method:: engine.setLocale(locale)
|
||||
This is akin the user pressing the close button in the window manager, and will
|
||||
have no effect if the engine has crashed, or is stuck in a loop.
|
||||
|
||||
Specify a language code to select the proper localization for the game.
|
||||
Engine configuration
|
||||
--------------------
|
||||
|
||||
.. seealso:: Complete list of :ref:`supported locales <doc_locales>`.
|
||||
An object used to configure the Engine instance based on godot export options, and to override those in custom HTML
|
||||
templates if needed.
|
||||
|
||||
:param string locale:
|
||||
Language code.
|
||||
Properties
|
||||
^^^^^^^^^^
|
||||
|
||||
.. js:method:: engine.setExecutableName(execName)
|
||||
+-------------------+-------------------------------+
|
||||
| type | name |
|
||||
+-------------------+-------------------------------+
|
||||
| boolean | :js:attr:`unloadAfterInit` |
|
||||
+-------------------+-------------------------------+
|
||||
| HTMLCanvasElement | :js:attr:`canvas` |
|
||||
+-------------------+-------------------------------+
|
||||
| string | :js:attr:`executable` |
|
||||
+-------------------+-------------------------------+
|
||||
| string | :js:attr:`mainPack` |
|
||||
+-------------------+-------------------------------+
|
||||
| string | :js:attr:`locale` |
|
||||
+-------------------+-------------------------------+
|
||||
| number | :js:attr:`canvasResizePolicy` |
|
||||
+-------------------+-------------------------------+
|
||||
| Array.<string> | :js:attr:`args` |
|
||||
+-------------------+-------------------------------+
|
||||
| function | :js:attr:`onExecute` |
|
||||
+-------------------+-------------------------------+
|
||||
| function | :js:attr:`onExit` |
|
||||
+-------------------+-------------------------------+
|
||||
| function | :js:attr:`onProgress` |
|
||||
+-------------------+-------------------------------+
|
||||
| function | :js:attr:`onPrint` |
|
||||
+-------------------+-------------------------------+
|
||||
| function | :js:attr:`onPrintError` |
|
||||
+-------------------+-------------------------------+
|
||||
|
||||
Specify the virtual filename of the executable. By default, the base name
|
||||
of the loaded engine files is used.
|
||||
.. js:attribute:: EngineConfig
|
||||
|
||||
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`.
|
||||
The Engine configuration object. This is just a typedef, create it like a regular object, e.g.:
|
||||
|
||||
:param string execName:
|
||||
Executable name.
|
||||
``const MyConfig = { executable: 'godot', unloadAfterInit: false }``
|
||||
|
||||
.. js:method:: engine.setProgressFunc(callback)
|
||||
**Property Descriptions**
|
||||
|
||||
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.
|
||||
.. js:attribute:: unloadAfterInit
|
||||
|
||||
If the callback function receives a total amount of bytes as 0, this means that
|
||||
it is impossible to calculate. Possible reasons include:
|
||||
Whether the unload the engine automatically after the instance is initialized.
|
||||
|
||||
- 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)
|
||||
:type: boolean
|
||||
|
||||
: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.
|
||||
:value: ``true``
|
||||
|
||||
.. js:method:: engine.setStdoutFunc(callback)
|
||||
.. js:attribute:: canvas
|
||||
|
||||
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.
|
||||
The HTML DOM Canvas object to use.
|
||||
|
||||
:param function callback:
|
||||
The callback function must accept one string argument: the message to print.
|
||||
By default, the first canvas element in the document will be used is none is specified.
|
||||
|
||||
.. js:method:: engine.setStderrFunc(callback)
|
||||
:type: HTMLCanvasElement
|
||||
|
||||
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.
|
||||
:value: ``null``
|
||||
|
||||
.. js:attribute:: executable
|
||||
|
||||
The name of the WASM file without the extension. (Set by Godot Editor export process).
|
||||
|
||||
:type: string
|
||||
|
||||
:value: ``""``
|
||||
|
||||
.. js:attribute:: mainPack
|
||||
|
||||
An alternative name for the game pck to load. The executable name is used otherwise.
|
||||
|
||||
:type: string
|
||||
|
||||
:value: ``null``
|
||||
|
||||
.. js:attribute:: locale
|
||||
|
||||
Specify a language code to select the proper localization for the game.
|
||||
|
||||
The browser locale will be used if none is specified. See complete list of
|
||||
:ref:`supported locales <doc_locales>`.
|
||||
|
||||
:type: string
|
||||
|
||||
:value: ``null``
|
||||
|
||||
.. js:attribute:: canvasResizePolicy
|
||||
|
||||
The canvas resize policy determines how the canvas should be resized by Godot.
|
||||
|
||||
``0`` means Godot won't do any resizing. This is useful if you want to control the canvas size from
|
||||
javascript code in your template.
|
||||
|
||||
``1`` means Godot will resize the canvas on start, and when changing window size via engine functions.
|
||||
|
||||
``2`` means Godot will adapt the canvas size to match the whole browser window.
|
||||
|
||||
:type: number
|
||||
|
||||
:value: ``2``
|
||||
|
||||
.. js:attribute:: args
|
||||
|
||||
The arguments to be passed as command line arguments on startup.
|
||||
|
||||
See :ref:`command line tutorial <doc_command_line_tutorial>`.
|
||||
|
||||
**Note**: :js:meth:`startGame <Engine.prototype.startGame>` will always add the ``--main-pack`` argument.
|
||||
|
||||
:type: Array.<string>
|
||||
|
||||
:value: ``[]``
|
||||
|
||||
.. js:function:: onExecute( path, args )
|
||||
|
||||
A callback function for handling Godot's ``OS.execute`` calls.
|
||||
|
||||
This is for example used in the Web Editor template to switch between project manager and editor, and for running the game.
|
||||
|
||||
:param string path:
|
||||
The path that Godot's wants executed.
|
||||
|
||||
:param Array.<string> args:
|
||||
The arguments of the "command" to execute.
|
||||
|
||||
.. js:function:: onExit( status_code )
|
||||
|
||||
A callback function for being notified when the Godot instance quits.
|
||||
|
||||
**Note**: This function will not be called if the engine crashes or become unresponsive.
|
||||
|
||||
:param number status_code:
|
||||
The status code returned by Godot on exit.
|
||||
|
||||
.. js:function:: onProgress( current, total )
|
||||
|
||||
A callback function for displaying download progress.
|
||||
|
||||
The function is called once per frame while downloading files, so 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 number current:
|
||||
The current amount of downloaded bytes so far.
|
||||
|
||||
:param number total:
|
||||
The total amount of bytes to be downloaded.
|
||||
|
||||
.. js:function:: onPrint( [ ...var_args ] )
|
||||
|
||||
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 * var_args:
|
||||
A variadic number of arguments to be printed.
|
||||
|
||||
.. js:function:: onPrintError( [ ...var_args ] )
|
||||
|
||||
A callback function for handling the standard error stream. This method should usually only be used in debug pages.
|
||||
|
||||
By default, ``console.error()`` is used.
|
||||
|
||||
:param * var_args:
|
||||
A variadic number of arguments to be printed as errors.
|
||||
|
||||
:param function callback:
|
||||
The callback function must accept one string argument: the message to print.
|
||||
|
||||
Reference in New Issue
Block a user