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

Merge pull request #4797 from Faless/js/3.2_reverts

Browse Source 
[3.2] Reverts HTML5 changes, fix github links
This commit is contained in:
Rémi Verschelde
2021-03-31 18:46:08 +02:00
committed by GitHub
parent 944d5e71c9 57b17e5af7
commit 5b82e9d2a1
2 changed files with 172 additions and 258 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
tutorials/platform/customizing_html5_shell.rst
View File

@@ -19,9 +19,9 @@ Some use-cases where customizing the default page is useful include:
- Passing custom command line arguments, e.g. ``-s`` to start a ``MainLoop`` script.
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>`__
`/misc/dist/html/full-size.html <https://github.com/godotengine/godot/blob/3.2/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>`__.
`/misc/dist/html/fixed-size.html <https://github.com/godotengine/godot/blob/3.2/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

426
tutorials/platform/html5_shell_classref.rst
View File

@@ -3,7 +3,7 @@
HTML5 shell class reference
===========================
Projects exported for the Web expose the :js:class:`Engine` class to the JavaScript environment, that allows
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
@@ -19,334 +19,248 @@ see :ref:`Custom HTML page for Web export <doc_customizing_html5_shell>`.
Static Methods
^^^^^^^^^^^^^^
+---------+-----------------------------------------------------------------------------------------------+
| Promise | :js:attr:`load <Engine.load>` **(** string basePath **)** |
+---------+-----------------------------------------------------------------------------------------------+
| void | :js:attr:`unload <Engine.unload>` **(** **)** |
+---------+-----------------------------------------------------------------------------------------------+
| boolean | :js:attr:`isWebGLAvailable <Engine.isWebGLAvailable>` **(** *[ number majorVersion=1 ]* **)** |
+---------+-----------------------------------------------------------------------------------------------+
+---------+-------------------------------------------------------------------------------------------------------------------+
| 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
^^^^^^^^^^^^^^^^
+---------+---------------------------------------------------------------------------------------------------------------+
| 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>` **(** **)** |
+---------+---------------------------------------------------------------------------------------------------------------+
+---------+------------------------------------------------------------------------------------------------------+
| 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 **)** |
+---------+------------------------------------------------------------------------------------------------------+
.. js:class:: Engine( initConfig )
Create a new Engine instance with the given configuration.
Static Method Descriptions
^^^^^^^^^^^^^^^^^^^^^^^^^^
:param EngineConfig initConfig:
The initial config for this instance.
.. js:method:: Engine.load(basePath)
**Static Methods**
Load the engine from the specified base path.
.. js:function:: load( basePath )
:param string basePath:
Base path of the engine to load.
:returns:
Promise which resolves once the engine is loaded.
Load the engine from the specified base path.
.. js:method:: Engine.unload()
:param string basePath:
Base path of the engine to load.
Unload the engine to free memory.
:return:
A Promise that resolves once the engine is loaded.
This method is called automatically once the engine is started unless
explicitly disabled using :js:meth:`engine.setUnloadAfterInit`.
:rtype: Promise
.. js:method:: Engine.isWebGLAvailable([majorVersion = 1])
.. js:function:: unload( )
Check whether WebGL is available. Optionally, specify a particular version of WebGL to check for.
Unload the engine to free memory.
: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.
This method will be called automatically depending on the configuration. See :js:attr:`unloadAfterInit`.
.. js:method:: Engine.setWebAssemblyFilenameExtension(extension)
.. js:function:: isWebGLAvailable( [ majorVersion=1 ] )
Set an alternative filename extension for the WebAssembly module. By default
it is assumed to be ``wasm``.
Check whether WebGL is available. Optionally, specify a particular version of WebGL to check for.
:param string extension:
Filename extension without preceding dot.
:param number majorVersion:
The major WebGL version to check for.
:return:
If the given major version of WebGL is available.
Instance Property Descriptions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
:rtype: boolean
.. js:attribute:: engine.rtenv
**Instance Methods**
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.
.. js:function:: prototype.init( [ basePath ] )
Instance Method Descriptions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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`.
.. js:class:: Engine
:param string basePath:
Base path of the engine to load.
Create a new instance of the ``Engine`` class.
:return:
A ``Promise`` that resolves once the engine is loaded and initialized.
.. js:method:: engine.init([basePath])
:rtype: Promise
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`.
.. js:function:: prototype.preloadFile( file [, path ] )
:param string basePath:
Base path of the engine to load.
Load a file so it is available in the instance's file system once it runs. Must be called **before** starting the
instance.
:returns:
Promise that resolves once the engine is loaded and initialized.
If not provided, the ``path`` is derived from the URL of the loaded file.
.. js:method:: engine.preloadFile(file[, path])
:param string\|ArrayBuffer file:
The file to preload.
Load a file so it is available in the instance's file system once it runs. Must
be called **before** starting the instance.
If a ``string`` the file will be loaded from that path.
:param string|ArrayBuffer file:
If type is ``string``, the file will be loaded from that path.
If an ``ArrayBuffer`` or a view on one, the buffer will used as the content of the file.
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.
: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.
:return:
A Promise that resolves once the file is loaded.
:returns:
Promise that resolves once the file is loaded.
:rtype: Promise
.. js:method:: engine.start([arg1, arg2, …])
.. js:function:: prototype.start( override )
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.
Start the engine instance using the given override configuration (if any).
:js:meth:`startGame <Engine.prototype.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.
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.
Fails if a canvas cannot be found on the page.
Fails if a canvas cannot be found on the page, or not specified in the configuration.
:param string variadic:
Command line argument.
:param EngineConfig override:
An optional configuration override.
:returns:
Promise that resolves once the engine started.
:return:
Promise that resolves once the engine started.
.. js:method:: engine.startGame(execName, mainPack)
:rtype: Promise
Start the game instance using the given executable URL and main pack URL.
.. js:function:: prototype.startGame( override )
This will initialize the instance if it is not initialized. For manual
initialization, see :js:meth:`engine.init`.
Start the game instance using the given configuration override (if any).
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.
This will initialize the instance if it is not initialized. For manual initialization, see :js:meth:`init <Engine.prototype.init>`.
:param string execName:
Executable name in a form of URL, omitting filename extension.
This will load the engine if it is not loaded, and preload the main pck.
:param string mainPack:
URL of the main pack to start the game.
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).
:returns:
Promise that resolves once the game started.
:param EngineConfig override:
An optional configuration override.
.. js:method:: engine.setUnloadAfterInit(enabled)
:return:
Promise that resolves once the game started.
Specify whether the engine will be unloaded automatically after the
instance is initialized. Enabled by default.
:rtype: Promise
:param boolean enabled:
``true`` if the engine shall be unloaded after initializing,
``false`` otherwise.
.. js:function:: prototype.copyToFS( path, buffer )
.. js:method:: engine.setCanvas(canvasElem)
Create a file at the specified ``path`` with the passed as ``buffer`` in the instance's file system.
Specify a canvas HTML element to use. By default, the first canvas element
on the page is used for rendering.
:param string path:
The location where the file will be created.
:param HTMLCanvasElement canvasElem:
The canvas element to use.
:param ArrayBuffer buffer:
The content of the file.
.. js:method:: engine.setCanvasResizedOnStart(enabled)
.. js:function:: prototype.requestQuit( )
Specifies whether the canvas will be resized to the width and height
specified in the project settings on start. Enabled by default.
Request that the current instance quit.
:param boolean enabled:
``true`` if the canvas shall be resized on start, ``false`` otherwise.
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.
.. js:method:: engine.setLocale(locale)
Engine configuration
--------------------
Specify a language code to select the proper localization for the game.
An object used to configure the Engine instance based on godot export options, and to override those in custom HTML
templates if needed.
.. seealso:: Complete list of :ref:`supported locales <doc_locales>`.
Properties
^^^^^^^^^^
:param string locale:
Language code.
+-------------------+-------------------------------+
| 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` |
+-------------------+-------------------------------+
.. js:method:: engine.setExecutableName(execName)
.. js:attribute:: EngineConfig
Specify the virtual filename of the executable. By default, the base name
of the loaded engine files is used.
The Engine configuration object. This is just a typedef, create it like a regular object, e.g.:
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`.
``const MyConfig = { executable: 'godot', unloadAfterInit: false }``
:param string execName:
Executable name.
**Property Descriptions**
.. js:method:: engine.setProgressFunc(callback)
.. js:attribute:: unloadAfterInit
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.
Whether the unload the engine automatically after the instance is initialized.
If the callback function receives a total amount of bytes as 0, this means that
it is impossible to calculate. Possible reasons include:
:type: boolean
- 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)
:value: ``true``
: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:attribute:: canvas
.. js:method:: engine.setStdoutFunc(callback)
The HTML DOM Canvas object to use.
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.
By default, the first canvas element in the document will be used is none is specified.
:param function callback:
The callback function must accept one string argument: the message to print.
:type: HTMLCanvasElement
.. js:method:: engine.setStderrFunc(callback)
: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.
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.