Merge pull request #328 from eska014/web-2.1

Update web export docs for 2.1

reference/compiling_for_web.rst

@@ -1,7 +1,7 @@
 .. _doc_compiling_for_web:
 
 Compiling for the Web
-========================
+=====================
 
 .. highlight:: shell
 
@@ -40,58 +40,63 @@ build or ``release_debug`` for a debug build::
 
 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.js`` for release or ``godot.javascript.opt.debug.js``
-for debug. Additionally, a file of the same name but with the extension
-``.html.mem`` will be generated.
+``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 4 files:
+these 5 files:
 
-1. ``godot.js`` — This is the file that was just compiled, but under a different
-   name.
+1. ``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.js godot.js
+       cp bin/godot.javascript.opt.asm.js godot.asm.js
 
    For the debug template::
 
-       cp bin/godot.javascript.opt.debug.js godot.js
+       cp bin/godot.javascript.opt.debug.asm.js godot.asm.js
 
-2. ``godot.mem`` — Another file created during compilation. This file initially
-   has the same name as the JavaScript file, except ``.js`` is replaced by
-   ``.html.mem``.
+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``.
 
    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
 
-3. ``godot.html`` and
-4. ``godotfs.js`` — Both of these files are located within the Godot Engine
-   repository, under ``tools/html_fs/``.
+4. ``godot.html``
+5. ``godotfs.js`` — Both of these files are located within the Godot Engine
+   repository, under ``tools/dist/html_fs/``.
 
 ::
 
-    cp tools/html_fs/godot.html .
-    cp tools/html_fs/godotfs.js .
+    cp tools/dist/html_fs/godot.html .
+    cp tools/dist/html_fs/godotfs.js .
 
-Once these 4 files are assembled, zip them up and your export template is ready
+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 godot.js godot.mem godotfs.js godot.html
+    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 godot.js godot.mem godotfs.js godot.html
+    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::
@@ -110,15 +115,17 @@ Customizing the HTML page
 -------------------------
 
 Rather than the default ``godot.html`` file from the Godot Engine repository's
-``tools/html_fs/`` directory, it is also possible to use a custom HTML page.
-This allows drastic customization of the final web presentation.
+``tools/dist/html_fs/`` directory, it is also possible to use a custom HTML
+page. This allows drastic customization of the final web presentation.
 
-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
+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 a good example to start off with, separating the
+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.
+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:
@@ -156,7 +163,7 @@ substituted by values dependent on the export:
 |                              | terminating semicolon                         |
 +------------------------------+-----------------------------------------------+
 | ``$GODOT_STYLE_INCLUDE``     | Custom string to include just before the end  |
-|                              | of the page's CSS style sheet                 |
+|                              | of the page's CSS                             |
 +------------------------------+-----------------------------------------------+
 
 The first five of the placeholders listed should always be implemented in the

tutorials/asset_pipeline/_export.rst

@@ -12,7 +12,7 @@ Export
    exporting_for_android
    exporting_for_ios
    exporting_for_uwp
+   exporting_for_web
 .. exporting_for_bb10
 .. exporting_for_nacl
-.. exporting_for_html5
 .. exporting_for_consoles

tutorials/asset_pipeline/exporting_for_web.rst

@@ -0,0 +1,61 @@
+.. _doc_exporting_for_web:
+
+Exporting for the Web
+=====================
+
+Exporting for the web generates several files to be served from a web server,
+including a default HTML page for presentation. A custom HTML file can be
+used, see :ref:`doc_compiling_for_web`.
+
+The default HTML file is designed to fit the game perfectly without cutting off
+parts of the canvas when the browser window is scaled to the game's dimensions.
+This way it can be inserted into an ``<iframe>`` with the game's size, as is
+common on most web game hosting sites.
+
+Serving the files
+-----------------
+
+The default ``.html`` file can be used as ``DirectoryIndex`` and can be
+renamed to e.g. ``index.html`` at any time, its name is never depended on.
+It can also be inserted into another HTML file as an ``<iframe>`` element.
+Users must allow **third-party** cookies when playing a game presented in an
+iframe.
+
+The ``.mem`` and ``.pck`` files are binary, usually delivered with MIME-type
+``application/octet-stream``.
+
+Delivering the files with gzip compression is recommended especially for the
+``.pck``, ``.asm.js`` and ``.mem`` files, which are usually large in size.
+
+Export options
+--------------
+
+Turning on **Debugging Enabled** when exporting will display a debug output
+below the canvas, displaying JavaScript and engine errors. If controls are
+enabled as well, display of this output can be toggled.
+
+**Memory Size** is fixed and must thus be set during export. Try using no more
+than necessary to strain users' browsers as little as possible.
+
+**Enable Run** will add a button between the *Stop scene* and *Play edited Scene*
+buttons in the editor to quickly open the game in the default browser for
+testing.
+
+The remaining options customize the generated HTML page:
+
+**Title** is the content of the ``<title>`` element of the page, usually used by
+browsers as the tab and window name. The title set here is only displayed until
+the game is started, afterwards the title is set to the application name set in
+the project settings.
+
+**Head Include** and **Style Include** are appended into the ``<head>`` and
+CSS ``<style>`` elements respectively. This allows, for example, linking
+web fonts for use in the page.
+
+**Font Family** is the CSS ``font-family`` used on the page, without terminating
+semicolon.
+
+**Controls Enabled** toggles display of controls, offering e.g. a toggle for
+output display in debug mode and a fullscreen button.
+In the default page, the controls are displayed in the top-right corner on top
+of the canvas, which can get in the way in games that use the cursor.