From 6d02c860e3ad268ad9d9a0ad635c2cce5547d00d Mon Sep 17 00:00:00 2001 From: Fabio Alessandrelli Date: Wed, 24 Feb 2021 00:12:06 +0100 Subject: [PATCH] Update HTML5 classref with autogenerated jsdoc. --- tutorials/platform/html5_shell_classref.rst | 426 ++++++++++++-------- 1 file changed, 256 insertions(+), 170 deletions(-) diff --git a/tutorials/platform/html5_shell_classref.rst b/tutorials/platform/html5_shell_classref.rst index 71f342e77..1a52a65e4 100644 --- a/tutorials/platform/html5_shell_classref.rst +++ b/tutorials/platform/html5_shell_classref.rst @@ -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 `. 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 ` **(** string basePath **)** | ++---------+-----------------------------------------------------------------------------------------------+ +| void | :js:attr:`unload ` **(** **)** | ++---------+-----------------------------------------------------------------------------------------------+ +| boolean | :js:attr:`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 ` **(** *[ string basePath ]* **)** | ++---------+---------------------------------------------------------------------------------------------------------------+ +| Promise | :js:attr:`preloadFile ` **(** string\|ArrayBuffer file *[, string path ]* **)** | ++---------+---------------------------------------------------------------------------------------------------------------+ +| Promise | :js:attr:`start ` **(** EngineConfig override **)** | ++---------+---------------------------------------------------------------------------------------------------------------+ +| Promise | :js:attr:`startGame ` **(** EngineConfig override **)** | ++---------+---------------------------------------------------------------------------------------------------------------+ +| void | :js:attr:`copyToFS ` **(** string path, ArrayBuffer buffer **)** | ++---------+---------------------------------------------------------------------------------------------------------------+ +| void | :js:attr:`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 `__ 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 ` 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 `. + 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 `. - :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 `. +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. | :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() ` - 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 `. + + :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 `. + + **Note**: :js:meth:`startGame ` will always add the ``--main-pack`` argument. + + :type: Array. + + :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. 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.