2016-03-04 12:14:46 +01:00
|
|
|
.. _doc_compiling_for_web:
|
|
|
|
|
2016-03-09 16:35:35 +01:00
|
|
|
Compiling for the Web
|
2017-01-12 22:20:07 +01:00
|
|
|
=====================
|
2016-03-04 12:14:46 +01:00
|
|
|
|
|
|
|
.. highlight:: shell
|
|
|
|
|
|
|
|
Requirements
|
|
|
|
------------
|
|
|
|
|
2016-03-09 16:35:35 +01:00
|
|
|
To compile export templates for the Web, the following is required:
|
2016-03-04 12:14:46 +01:00
|
|
|
|
2016-06-16 01:12:46 +02:00
|
|
|
- `Emscripten SDK <http://emscripten.org/>`__ (Install in a path without
|
|
|
|
spaces, i.e. not on "Program Files")
|
2016-03-04 12:14:46 +01:00
|
|
|
- `Python 2.7+ <https://www.python.org/>`__ (3.0 is
|
|
|
|
untested as of now)
|
|
|
|
- `SCons <http://www.scons.org>`__ build system
|
|
|
|
|
|
|
|
Compiling
|
|
|
|
---------
|
|
|
|
|
|
|
|
Start a terminal and set the environment variable ``EMSCRIPTEN_ROOT`` to the
|
|
|
|
installation directory of Emscripten::
|
|
|
|
|
|
|
|
export EMSCRIPTEN_ROOT=~/emsdk/emscripten/master
|
|
|
|
|
2016-06-16 01:12:46 +02:00
|
|
|
If you are on Windows, start a regular prompt or the Emscripten Command Prompt.
|
|
|
|
Do **not** use the Developer Command Prompt nor any of the ones that come with
|
|
|
|
Visual Studio. You can set the environment variable in the system settings or
|
|
|
|
in the prompt itself::
|
|
|
|
|
|
|
|
set EMSCRIPTEN_ROOT=C:\emsdk\emscripten\master
|
|
|
|
|
2016-03-04 12:14:46 +01:00
|
|
|
Now go to the root directory of the engine source code and instruct SCons to
|
|
|
|
compile for JavaScript. Specify ``target`` as either ``release`` for a release
|
|
|
|
build or ``release_debug`` for a debug build::
|
|
|
|
|
|
|
|
scons platform=javascript tools=no target=release
|
|
|
|
scons platform=javascript tools=no target=release_debug
|
|
|
|
|
|
|
|
The engine will now be compiled to JavaScript by Emscripten. If all goes well,
|
|
|
|
the resulting file will be placed in the ``bin`` subdirectory. Its name is
|
2017-01-12 22:20:07 +01:00
|
|
|
``godot.javascript.opt.asm.js`` for release or
|
|
|
|
``godot.javascript.opt.debug.asm.js`` for debug. Additionally, two files of
|
|
|
|
the same name but with the extensions ``.js`` and ``.html.mem`` will be
|
|
|
|
generated.
|
2016-03-04 12:14:46 +01:00
|
|
|
|
|
|
|
Building export templates
|
|
|
|
-------------------------
|
|
|
|
|
|
|
|
After compiling, further steps are required to build the template.
|
|
|
|
The actual web export template has the form of a zip file containing at least
|
2017-01-12 22:20:07 +01:00
|
|
|
these 5 files:
|
2016-03-04 12:14:46 +01:00
|
|
|
|
2017-01-12 22:20:07 +01:00
|
|
|
1. ``godot.asm.js`` — This is the file that was just compiled, but under a
|
|
|
|
different name.
|
2016-03-04 12:14:46 +01:00
|
|
|
|
|
|
|
For the release template::
|
|
|
|
|
2017-01-12 22:20:07 +01:00
|
|
|
cp bin/godot.javascript.opt.asm.js godot.asm.js
|
2016-03-04 12:14:46 +01:00
|
|
|
|
|
|
|
For the debug template::
|
|
|
|
|
2017-01-12 22:20:07 +01:00
|
|
|
cp bin/godot.javascript.opt.debug.asm.js godot.asm.js
|
2016-03-04 12:14:46 +01:00
|
|
|
|
2017-01-12 22:20:07 +01:00
|
|
|
2. ``godot.js``
|
|
|
|
3. ``godot.mem`` — other files created during compilation, initially with the
|
|
|
|
same name as the ``.asm.js`` file, except ``.asm.js`` is replaced by
|
|
|
|
``.js`` for ``godot.js`` and ``.html.mem`` for
|
|
|
|
``godot.mem``.
|
2016-03-04 12:14:46 +01:00
|
|
|
|
|
|
|
For the release template::
|
|
|
|
|
2017-01-12 22:20:07 +01:00
|
|
|
cp bin/godot.javascript.opt.js godot.js
|
2016-03-04 12:14:46 +01:00
|
|
|
cp bin/godot.javascript.opt.html.mem godot.mem
|
|
|
|
|
|
|
|
For the debug template::
|
|
|
|
|
2017-01-12 22:20:07 +01:00
|
|
|
cp bin/godot.javascript.opt.debug.js godot.js
|
2016-03-04 12:14:46 +01:00
|
|
|
cp bin/godot.javascript.opt.debug.html.mem godot.mem
|
|
|
|
|
2017-01-12 22:20:07 +01:00
|
|
|
4. ``godot.html``
|
|
|
|
5. ``godotfs.js`` — Both of these files are located within the Godot Engine
|
|
|
|
repository, under ``tools/dist/html_fs/``.
|
2016-03-04 12:14:46 +01:00
|
|
|
|
|
|
|
::
|
|
|
|
|
2017-01-12 22:20:07 +01:00
|
|
|
cp tools/dist/html_fs/godot.html .
|
|
|
|
cp tools/dist/html_fs/godotfs.js .
|
2016-03-04 12:14:46 +01:00
|
|
|
|
2017-01-12 22:20:07 +01:00
|
|
|
Once these 5 files are assembled, zip them up and your export template is ready
|
2016-03-04 12:14:46 +01:00
|
|
|
to go. The correct name for the template file is ``javascript_release.zip`` for
|
|
|
|
the release template::
|
|
|
|
|
2017-01-12 22:20:07 +01:00
|
|
|
zip javascript_release.zip godot.asm.js godot.js godot.mem godotfs.js godot.html
|
2016-03-04 12:14:46 +01:00
|
|
|
|
|
|
|
And ``javascript_debug.zip`` for the debug template::
|
|
|
|
|
2017-01-12 22:20:07 +01:00
|
|
|
zip javascript_debug.zip godot.asm.js godot.js godot.mem godotfs.js godot.html
|
2016-03-04 12:14:46 +01:00
|
|
|
|
|
|
|
The resulting files must be placed in the ``templates`` directory in your Godot
|
|
|
|
user directory::
|
|
|
|
|
2016-03-09 16:35:35 +01:00
|
|
|
mv javascript_release.zip ~/.godot/templates
|
|
|
|
mv javascript_debug.zip ~/.godot/templates
|
2016-03-04 12:14:46 +01:00
|
|
|
|
|
|
|
If you are writing custom modules or using custom C++ code, you may want to
|
|
|
|
configure your zip files as custom export templates. This can be done in the
|
|
|
|
export GUI, using the "Custom Package" option.
|
|
|
|
There's no need to copy the templates in this case — you can simply reference
|
|
|
|
the resulting files in your Godot source folder, so the next time you build,
|
|
|
|
the custom templates will already be referenced.
|
|
|
|
|
|
|
|
Customizing the HTML page
|
|
|
|
-------------------------
|
|
|
|
|
|
|
|
Rather than the default ``godot.html`` file from the Godot Engine repository's
|
2017-01-12 22:20:07 +01:00
|
|
|
``tools/dist/html_fs/`` directory, it is also possible to use a custom HTML
|
|
|
|
page. This allows drastic customization of the final web presentation.
|
2016-03-04 12:14:46 +01:00
|
|
|
|
2017-01-12 22:20:07 +01:00
|
|
|
In the HTML page, the JavaScript object ``Module`` is the page's interface to
|
|
|
|
Emscripten. Check the official documentation for information on how to use it:
|
|
|
|
https://kripken.github.io/emscripten-site/docs/api_reference/module.html
|
2016-03-04 12:14:46 +01:00
|
|
|
|
2017-01-12 22:20:07 +01:00
|
|
|
The default HTML page offers an example to start off with, separating the
|
2016-03-04 12:14:46 +01:00
|
|
|
Emscripten interface logic in the JavaScript ``Module`` object from the page
|
2017-01-12 22:20:07 +01:00
|
|
|
logic in the ``Presentation`` object. Emscripten's default ``shell.html`` file
|
|
|
|
is another example, but does not use Godot's placeholders, listed below.
|
2016-03-04 12:14:46 +01:00
|
|
|
|
|
|
|
When exporting a game, several placeholders in the ``godot.html`` file are
|
|
|
|
substituted by values dependent on the export:
|
|
|
|
|
|
|
|
+------------------------------+-----------------------------------------------+
|
|
|
|
| Placeholder | substituted by |
|
|
|
|
+==============================+===============================================+
|
|
|
|
| ``$GODOT_JS`` | Name of the compiled Godot Engine JavaScript |
|
|
|
|
| | file |
|
|
|
|
+------------------------------+-----------------------------------------------+
|
|
|
|
| ``$GODOT_FS`` | Name of the filesystem access JavaScript |
|
|
|
|
| | file |
|
|
|
|
+------------------------------+-----------------------------------------------+
|
|
|
|
| ``$GODOT_MEM`` | Name of the memory initialization file |
|
|
|
|
+------------------------------+-----------------------------------------------+
|
|
|
|
| ``$GODOT_CANVAS_WIDTH`` | Integer specifying the initial display width |
|
|
|
|
| | of the game |
|
|
|
|
+------------------------------+-----------------------------------------------+
|
|
|
|
| ``$GODOT_CANVAS_HEIGHT`` | Integer specifying the initial display height |
|
|
|
|
| | of the game |
|
|
|
|
+------------------------------+-----------------------------------------------+
|
|
|
|
| ``$GODOT_DEBUG_ENABLED`` | String ``true`` if debugging, ``false`` |
|
|
|
|
| | otherwise |
|
|
|
|
+------------------------------+-----------------------------------------------+
|
|
|
|
| ``$GODOT_CONTROLS_ENABLED`` | String ``true`` if ``html/controls_enabled`` |
|
|
|
|
| | is enabled, ``false`` otherwise |
|
|
|
|
+------------------------------+-----------------------------------------------+
|
|
|
|
| ``$GODOT_HEAD_TITLE`` | Title of the page, normally used as content |
|
|
|
|
| | of the HTML ``<title>`` element |
|
|
|
|
+------------------------------+-----------------------------------------------+
|
|
|
|
| ``$GODOT_HEAD_INCLUDE`` | Custom string to include just before the end |
|
|
|
|
| | of the HTML ``<head>`` element |
|
|
|
|
+------------------------------+-----------------------------------------------+
|
|
|
|
| ``$GODOT_STYLE_FONT_FAMILY`` | CSS format ``font-family`` to use, without |
|
|
|
|
| | terminating semicolon |
|
|
|
|
+------------------------------+-----------------------------------------------+
|
|
|
|
| ``$GODOT_STYLE_INCLUDE`` | Custom string to include just before the end |
|
2017-01-12 22:20:07 +01:00
|
|
|
| | of the page's CSS |
|
2016-03-04 12:14:46 +01:00
|
|
|
+------------------------------+-----------------------------------------------+
|
|
|
|
|
|
|
|
The first five of the placeholders listed should always be implemented in the
|
|
|
|
HTML page, since they are important for the correct presentation of the game.
|
|
|
|
The other placeholders are optional.
|
|
|
|
|
|
|
|
Finally, the custom HTML page is installed by replacing the existing
|
|
|
|
``godot.html`` file in the export template with the new one, retaining the name
|
|
|
|
of the original.
|