Skip to main content Link Search Menu Expand Document (external link)
TAC 380

Theme: auto

Building for the Web

Emscripten is a C++ to WebAssembly compiler. SDL and other libraries we use work in Emscripten, so you can compile your C++ games to run in a web browser! This is what this site uses for the in-browser playable versions of the game.

In order to get your games working with Emscripten, there are some minor Emscripten-specific code changes required, which this guide outlines.

I’ve only extensively tested this process on a Mac, but it does also work fine on Windows, too. Let me know if there are issues!

Installing the Emscripten SDK

First, you need to install the Emscripten SDK (emsdk) following these instructions. On Mac, you should issue the commands from terminal whereas on Windows, use a normal Windows Command prompt (and not Git Bash).

Make sure you keep track of where you installed emsdk, as you will need this path later. If you’re on Mac/Linux, I’d suggest just starting from your ~ directory (your user’s home directory), so that everything can be relative to that path.

C++ Code Changes

While not required, you may want to make some minor changes to the C++ code of every game you want to build for Emscripten.

Disabling ESC to Quit

For the Emscripten version of your games, you may want to disable the functionality where the ESC button exits the game. This is particularly the case for labs 9 through 12, which capture the mouse in the browser window. To get mouse control back, the user has to press ESC, which would mean the game would end. You can compile out this code on Emscripten using #ifndef __EMSCRIPTEN__. It will look something like this:

#ifndef __EMSCRIPTEN__
	if (state[SDL_SCANCODE_ESCAPE])
	{
		mIsRunning = false;
	}
#endif

Configuring CMake

The instructions on how to run CMake are different depending on whether you’re on Mac or Windows.

Mac

Open a terminal and cd to the directory which contains your TAC 380 repo. Then, cd to the lab that you want to build. For example, if you’re building Lab 4 you would do cd Lab04.

Run CMake with:

emcmake cmake -DCMAKE_BUILD_TYPE=Release -B embuild

Windows

First, you need to install Visual Studio. You can follow the same steps on as for Making a Standalone Build.

First, you should edit your PATH environment variable (see here if you don’t know how) to include the location of the CMake and Ninja. If you’re using Visual Studio 2022, the locations you want to add to PATH are:

  • C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin
  • C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\CommonExtensions\Microsoft\CMake\Ninja

Be careful when you edit your PATH environment variable that you do not accidentally overwrite the existing entries. You just want to add to the PATH.

Then, find the location in Windows Explorer where emsdk is and double click on emcmdprompt.bat to open up the “Emscripten Command Prompt.”

After you open this, cd to the directory that contains your TAC 380 repo. Then, cd to the lab that you want to build. For example, if you’re building Lab 4 you would do cd Lab04.Then run:

emcmake cmake -DCMAKE_BUILD_TYPE=Release -B embuild

Building/Testing for Emscripten

Once CMake is configured, you need to change directories to embuild:

cd embuild

From here, you can build with the following command:

cmake --build . -j8

Once the game is built, you can test it locally. However, because most browsers don’t allow loading of WebAssembly files from file://, you can’t directly load the HTML file directly into your browser. Instead, you need to use the emrun script which will spin up a web server that you can locally connect to for testing. To launch it for a specific game, use:

emrun --port 8080 LabXX.html

Where again, LabXX is the game you want to test. This should launch your browser, but if it doesn’t, you can go to http://localhost:8080 directly. From the main page’s file listing, click on the LabXX.html file. If it all worked properly, you should be able to play your game in browser. Note that you often will have to click once onto the game for sound effects and/or mouse capture to work.

Uploading to the Web

If you want to upload your game to your portfolio website, you just need to go into your embuild directory for the game in question. In here, you’ll see the following four files:

LabXX.html
LabXX.js
LabXX.wasm
LabXX.data

You should copy all four of these files and upload it to your site. Note that because Lab01 (Pong) doesn’t have any asset files, it will not have the .data file.

And that’s it! Let me know if you have any issues.