Skip to content

Web Deployment Guide

Jump to bottom
Peter Robinson edited this page Jun 1, 2020 · 1 revision

Introduction

This guide will show you the steps to setup your computer for deploying Torque 2D to a website. This information may slightly change during the development branch testing phase but this documentation is for people who want to start familiarizing themselves with the Emscripten platform early. The official release of Emscripten platform support will come with the master branch push of Torque 2D 3.0.

What is Emscripten?

Emscripten is an LLVM to JavaScript compiler. It takes LLVM bytecode (which can be generated from C/C++ using Clang, or any other language that can be converted into LLVM bytecode) and compiles that into JavaScript, which can be run on the web (or anywhere else JavaScript can run).

In order to compile you'll need the following:

  • Emscripten
  • Python2
  • Node.js
  • CMake
  • Pre-generated font files
  • Web server to run the resulting page

The required font files as well as older Emscripten changes are all supplied in a downloadable archive.

Setting up Emscripten

NOTE: these instructions assume you are using a Linux or OS X box. Other platforms may vary.

First you need to install Emscripten itself. The emscripten wiki is a good starting point.

For Windows users, a setup guide is available at the Emscripten wiki.

There is also a setup guide available for OSX users.

Linux developers can follow this setup guide.

NOTE: keep in mind the tutorials above are hosted on the Emscripten wiki - over time it is possible that they become out of date or contain other errors.

When you have the Emscripten toolchain setup, you'll need to modify engine/compilers/emscripten/generate.sh and engine/compilers/emscripten/generate_release.sh in order to point it to the emscripten toolchain. For example if you have emscripten installed in /Users/kork/emscripten, the top should look like this:

EMSCRIPTEN_PATH=/Users/kork/emscripten

Before building, make sure you have generated all the neccesary font files. The current list of fonts required is stored in the "FontAssetFiles" list in emscripten/assets/CMakeLists.txt. Failing that the downloadable archive includes a prebuilt set of required font files.

When you are ready to create a debug build, run the following from a terminal:

cd engine/compilers/emscripten
sh ./generate.sh
make

Or if you want to make a release build:

cd engine/compilers/emscripten
sh ./generate_release.sh
make

After a long while you should get several files in the Torque 2D emscripten folder, the most important ones being "Torque2D.html", "Torque2D.js" and "Torque2D.data". If you want to test things out, simply copy these files to a web server and open Torque2D.html. Alternatively you can use python to start a http server and check it out, e.g.:

python -m SimpleHTTPServer

Then open http://(the address)/Torque2D.html

Browser Support

Torque 2D compiled with Emscripten runs on any browser with WebGL support. Chrome and Firefox offer the best performance at the moment. In Safari, WebGL is disabled by default. To enable it, in the Develop menu, select "Enable WebGL". Framerate performance in Safari is not very good right now.

Notes on the Emscripten platform

  1. Scrollers do not work currently. WebGL does not have support for clipping planes, which means to enable scroller functionally, a WebGL compliant rendering path would need to be coded.

  2. Making changes to scripts or adding/deleting assets requires recompiling with Emscripten. Before recompiling, delete or move the copies of "Torque2D.html", "Torque2D.js" and "Torque2D.data" in the compilers/emscripten folder as they are not automatically overwritten.

Clone this wiki locally