Compiling for the Web¶

Requirements¶

To compile export templates for the Web, the following is required:

Emscripten SDK (Install in a path without spaces, i.e. not on “Program Files”)
Python 2.7+ (3.0 is untested as of now)
SCons 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

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

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 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.

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 these 5 files:

godot.asm.js — This is the file that was just compiled, but under a different name.

For the release template:
```
cp bin/godot.javascript.opt.asm.js godot.asm.js
```
For the debug template:
```
cp bin/godot.javascript.opt.debug.asm.js godot.asm.js
```
godot.js
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.

For the release template:
```
cp bin/godot.javascript.opt.js       godot.js
cp bin/godot.javascript.opt.html.mem godot.mem
```
For the debug template:
```
cp bin/godot.javascript.opt.debug.js       godot.js
cp bin/godot.javascript.opt.debug.html.mem godot.mem
```
godot.html
godotfs.js — Both of these files are located within the Godot Engine repository, under tools/dist/html_fs/.

cp tools/dist/html_fs/godot.html .
cp tools/dist/html_fs/godotfs.js .

Once these 5 files are assembled, zip them up and your export template is ready to go. The correct name for the template file is javascript_release.zip for the release template:

zip javascript_release.zip godot.asm.js godot.js godot.mem godotfs.js godot.html

And javascript_debug.zip for the debug template:

zip javascript_debug.zip godot.asm.js godot.js godot.mem godotfs.js godot.html

The resulting files must be placed in the templates directory in your Godot user directory:

mv javascript_release.zip ~/.godot/templates
mv javascript_debug.zip ~/.godot/templates

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 tools/dist/html_fs/ directory, it is also possible to use a custom HTML page. This allows drastic customization of the final web presentation.

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

The default HTML page offers an example to start off with, separating the Emscripten interface logic in the JavaScript Module object from the page logic in the Presentation object. Emscripten’s default shell.html file is another example, but does not use Godot’s placeholders, listed below.

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 of the page’s CSS

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.