godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2026-01-04 14:11:02 +03:00
Code Issues Packages Projects Releases Wiki Activity

Improve naming and organization of some manual articles

Browse Source 
HTML5/Web moved to their own subfolder
Global Illumination moved to their own subfolder
UI, IO, Inputs sections titles adjusted
2D, 3D tutorials grouped to improve navigation
This commit is contained in:
Yuri Sizov
2023-02-26 17:13:58 +01:00
parent af256254cd
commit d524544e07
64 changed files with 104 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

212
tutorials/platform/web/customizing_html5_shell.rst Normal file
View File

@@ -0,0 +1,212 @@
:article_outdated: True
.. _doc_customizing_html5_shell:
Custom HTML page for Web export
====================================
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 easily be directly controlled from the outside yet,
such page allows to customize the initialization process for the engine.
Some use-cases where customizing the default page is useful include:
- 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.
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>`__
but the following template can be used as a much simpler example:
.. code-block:: html
<!DOCTYPE html>
<html>
<head>
<title>My Template</title>
<meta charset="UTF-8">
</head>
<body>
<canvas id="canvas"></canvas>
<script src="$GODOT_URL"></script>
<script>
var engine = new Engine($GODOT_CONFIG);
engine.startGame();
</script>
</body>
</html>
Setup
-----
As shown by the example above, it is mostly a regular HTML document, with few placeholders
which needs to be replaced during export, an html ``<canvas>`` element, and some simple
JavaScript code that calls the :js:class:`Engine` class.
The only required placeholders are:
- ``$GODOT_URL``:
The name of the main JavaScript file, which provides the :js:class:`Engine` class required
to start the engine and that must be included in the HTML as a ``<script>``.
The name is generated from the *Export Path* during the export process.
- ``$GODOT_CONFIG``:
A JavaScript object, containing the export options and can be later overridden.
See :js:attr:`EngineConfig` for the full list of overrides.
The following optional placeholders will enable some extra features in your custom HTML template.
- ``$GODOT_PROJECT_NAME``:
The project name as defined in the Project Settings. It is a good idea to use it as a ``<title>``
in your template.
- ``$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.
When the custom page is ready, it can be selected in the export options under the *Html / Custom Html Shell*
section.
.. image:: img/html5_export_options.png
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, but as shown here, most of them can be skipped depending on
how much customization is needed.
See the :ref:`HTML5 shell class reference <doc_html5_shell_classref>`, for the full list of methods and options available.
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 with the exported configuration, and then call the :js:meth:`engine.startGame <Engine.prototype.startGame>` method
optionally overriding any :js:attr:`EngineConfig` parameters.
.. code-block:: js
const engine = new Engine($GODOT_CONFIG);
engine.startGame({
/* optional override configuration, eg. */
// unloadAfterInit: false,
// canvasResizePolicy: 0,
// ...
});
This snippet of code automatically loads and initializes the engine before starting the game.
It uses the given configuration to to load the engine. The :js:meth:`engine.startGame <Engine.prototype.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.
In case your project needs to have special control over the start arguments and dependency files,
the :js:meth:`engine.start <Engine.prototype.start>` method can be used instead. Note, that this method do not
automatically preload the ``pck`` file, so you will probably want to manually preload it
(and any other extra file) via the :js:meth:`engine.preloadFile <Engine.prototype.preloadFile>` method.
Optionally, you can also manually :js:meth:`engine.init <Engine.prototype.init>` to perform specific actions after
the module initialization, but before the engine starts.
This process is a bit more complex, but gives you full control over the engine startup process.
.. code-block:: js
const myWasm = 'mygame.wasm';
const myPck = 'mygame.pck';
const engine = new Engine();
Promise.all([
// Load and init the engine
engine.init(myWasm),
// And the pck concurrently
engine.preloadFile(myPck),
]).then(() => {
// Now start the engine.
return engine.start({ args: ['--main-pack', myPck] });
}).then(() => {
console.log('Engine has started!');
});
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 if the share the same ``wasm``.
.. note:: Multiple instances cannot be spawned by default, as the engine is immediately unloaded after it is initialized.
To prevent this from happening see the :js:attr:`unloadAfterInit` override option. 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.
Customizing the behavior
------------------------
In the Web environment several methods can be used to guarantee that the game will work as intended.
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.
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:attr:`executable` override option can be
used to override this value.
Customizing the presentation
----------------------------
Several configuration options can be used to further customize the look and behavior of the game on your page.
By default, the first canvas element on the page is used for rendering. To use a different canvas
element the :js:attr:`canvas` override option can be used. It requires a reference to the DOM
element itself.
.. code-block:: js
const canvasElement = document.querySelector("#my-canvas-element");
engine.startGame({ canvas: canvasElement });
The way the engine resize the canvas can be configured via the :js:attr:`canvasResizePolicy`
override option.
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:attr:`onProgress` callback option, which
allows to set up a callback function that will be called regularly as the engine loads new bytes.
.. code-block:: js
function printProgress(current, total) {
console.log("Loaded " + current + " of " + total + " bytes");
}
engine.startGame({ onProgress: printProgress });
Be aware that in some cases ``total`` can be ``0``. This means that it cannot be calculated.
If your game supports multiple languages, the :js:attr:`locale` override option can be used to
force 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.
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.
Use the :js:attr:`onPrint` override option to set a callback function for the output stream,
and the :js:attr:`onPrintError` override option to set a callback function for the error stream.
.. code-block:: js
function print(text) {
console.log(text);
}
function printError(text) {
console.warn(text);
}
engine.startGame({ onPrint: print, onPrintError: printError });
When handling the engine output, keep in mind that it may not be desirable to print it out in the
finished product.

353
tutorials/platform/web/html5_shell_classref.rst Normal file
View File

@@ -0,0 +1,353 @@
:article_outdated: True
.. _doc_html5_shell_classref:
HTML5 shell class reference
===========================
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
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 | :js:attr:`load <Engine.load>` **(** string basePath **)** |
+---------+-----------------------------------------------------------------------------------------------+
| void | :js:attr:`unload <Engine.unload>` **(** **)** |
+---------+-----------------------------------------------------------------------------------------------+
| boolean | :js:attr:`isWebGLAvailable <Engine.isWebGLAvailable>` **(** *[ number majorVersion=1 ]* **)** |
+---------+-----------------------------------------------------------------------------------------------+
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>` **(** **)** |
+---------+---------------------------------------------------------------------------------------------------------------+
.. js:class:: Engine( initConfig )
Create a new Engine instance with the given configuration.
:param EngineConfig initConfig:
The initial config for this instance.
**Static Methods**
.. js:function:: load( basePath )
Load the engine from the specified base path.
:param string basePath:
Base path of the engine to load.
:return:
A Promise that resolves once the engine is loaded.
:rtype: Promise
.. js:function:: unload( )
Unload the engine to free memory.
This method will be called automatically depending on the configuration. See :js:attr:`unloadAfterInit`.
.. js:function:: 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.
:return:
If the given major version of WebGL is available.
:rtype: boolean
**Instance Methods**
.. js:function:: prototype.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.
:return:
A ``Promise`` that resolves once the engine is loaded and initialized.
:rtype: Promise
.. js:function:: prototype.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.
If not provided, the ``path`` is derived from the URL of the loaded file.
:param string\|ArrayBuffer file:
The file to preload.
If a ``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.
:param string path:
Path by which the file will be accessible. Required, if ``file`` is not a string.
:return:
A Promise that resolves once the file is loaded.
:rtype: Promise
.. js:function:: prototype.start( override )
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:`init <Engine.prototype.init>`.
The engine must be loaded beforehand.
Fails if a canvas cannot be found on the page, or not specified in the configuration.
:param EngineConfig override:
An optional configuration override.
:return:
Promise that resolves once the engine started.
:rtype: Promise
.. js:function:: prototype.startGame( override )
Start the game instance using the given configuration override (if any).
This will initialize the instance if it is not initialized. For manual initialization, see :js:meth:`init <Engine.prototype.init>`.
This will load the engine if it is not loaded, and preload the main pck.
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).
:param EngineConfig override:
An optional configuration override.
:return:
Promise that resolves once the game started.
:rtype: Promise
.. js:function:: prototype.copyToFS( path, buffer )
Create a file at the specified ``path`` with the passed as ``buffer`` in the instance's file system.
:param string path:
The location where the file will be created.
:param ArrayBuffer buffer:
The content of the file.
.. js:function:: prototype.requestQuit( )
Request that the current instance quit.
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.
Engine configuration
--------------------
An object used to configure the Engine instance based on godot export options, and to override those in custom HTML
templates if needed.
Properties
^^^^^^^^^^
+-------------------+-------------------------------+
| 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:attribute:: EngineConfig
The Engine configuration object. This is just a typedef, create it like a regular object, e.g.:
``const MyConfig = { executable: 'godot', unloadAfterInit: false }``
**Property Descriptions**
.. js:attribute:: unloadAfterInit
Whether the unload the engine automatically after the instance is initialized.
:type: boolean
:value: ``true``
.. js:attribute:: canvas
The HTML DOM Canvas object to use.
By default, the first canvas element in the document will be used is none is specified.
:type: HTMLCanvasElement
: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.

BIN
tutorials/platform/web/img/html5_export_options.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 26 KiB

13
tutorials/platform/web/index.rst Normal file
View File

@@ -0,0 +1,13 @@
:article_outdated: True
.. _doc_platform_html5:
HTML5
=====
.. toctree::
:maxdepth: 1
:name: toc-learn-features-platform-html5
html5_shell_classref
customizing_html5_shell