When porting your game to Emscripten, you will soon enough notice that the default virtual file system it use doesn’t persist data, everything you write in a file is lost from one session to another. Hopefully, Emscripten has a specific file system, called IDBFS which persist your data (using the HTML5 API Indexed Db). Now, it’s important to note that you have to call manually the sync operation, and also to handle the delay between the moment you call for synchronization and the moment data are effectively synchronized, since the API is asynchronous. For more details on Emscripten File System API, the official website offer a lot of informations :
Emscripten API

On my existing C games, I persist data through SQLite. The huge advantage of SQLite is that you can use SQL language to select / manage your data and take advantage of most DBMS functionalities without the need to have any kind of server running in the background, since everything in SQLite is saved on a single db file.

Using IDBFS, it’s possible to keep your entire existing SQLite management code, the only thing you need is to call Emscripten sync API when needed to persist any changes:

Initialisation of the IDBFS filesystem :

(the EM_ASM macro allow us to call JavaScript code within c)

At the first run, the “persistent_data” folder is always empty, you can’t mount a directory that is already mounted with the default virtual file system.

After synchronisation is done, you can either start using the existing files that are now into the “persistent_data” folder, or add the base data into your folder if it’s the first time a player run your game.

(the save_mngr function is the object that handle all my save data using SQLite)
(this code is put at the beginning of my gameloop function, since you have to wait for data to be synchronized, and that there is no proper way of waiting for code execution with Emscripten (the same way sleep() or a while loop would do on desktop versions))

After that, you can persist any changes to your SQLite file with this code, for example after any data insertion or data update :

and that’s all! The initialisation code will then load the modified SQLite data next time the player run the game. It’s possible to check Indexed Db content afterwards with Chrome, go to Developments tools > Resources tab > Indexed Db.

While I used Windows / Visual studio for porting my game engine, pretty much all advices listed here are valid for other platforms.

Tools used

• Emscripten 1.27.2
• emsdk for Windows
• Emscripten Visual studio 2010 plugin
• Chrome / Firefox for testing

If you never installed Emscripten before, go to the official website and follow the instructions described here:

Emscripten website

Important stuff before attempting a port

The most important thing to do before porting your engine to Emscripten is to make it cross-platform. Emscripten use clang to compile c code, which could be considered as a drop in replacement for GCC. It is also POSIX compliant, so if your base code is Windows only, it’s probably better to make it cross-platform first.

Things that DON’T WORK under Emscripten :

• Threads, so if you have some background resources loading, you will need to adapt / rework this portion of code, You can use web worker as a work around, but that won’t give you a fully fledged threading support
• plug-in system through dlopen / dlsym
• dynamic linking, every library must be compiled as a static LLVM bitcode file (.bc) and linked when you compile you game

That’s the stuff I ran into / noticed when porting my engine, there is more limitation to be aware of, for more details, see the porting guidelines on Emscripten website:

Porting guidelines

Which libraries I used in my C engine

These are the libraries that the desktop / mobile version of my engine use, Almost all these libraries worked through Emscripten with minor changes or were already included in Emscripten. Some still require specific configuration / build flags.

• glfw 3 (input / window management)
• chipmunk 6.2.1 (Physics)
• freetype 2.4.11 (ttf fonts support)
• lua 5.2.3 (Scripting)
• libogg 1.3.2 (Ogg decoding)
• libpng 1.6.2 (png image support)
• libvorbis 1.3.4 (Vorbis decoding)
• libsndfile 1.0.25 (Reading sound files)
• protobuf-c 0.15 (For custom binary file type like level data)
• sqlite 3 (file based SQL database, used for save files and localization files)
• libzip 0.11 (Reading zip archives)
• zlib 1.2.8 (Decoding zip)
• portaudio v19 (Playing audio content)

Porting libraries

All libraries are compiled as LLVM static bitcode (.bc file) it’s these files you provide to your game as input libraries when you will finally build it.

GLFW
Emscripten include glfw 2 and 3, so you don’t need to port it. Just compile your game with the option “-s USE_GLFW=3” (or 2 if your using GLFW 2)

Chipmunk
Chipmunk “almost” work out of the box, I made a specific patch to fix a bug I got with it.

The main bug with chipmunk / Emscripten is located in cpHashSetEach.c, emscripten doesn’t like the cpHashSetIteratorFunc function pointer and crashed for me right away. I fixed that by creating a specific cpHashSetIteratorFunc, replacing the void* type with the correct struct name. It also required me to create a specific header file with the struct definition so that cpHashSetEach.c and cpBBTree.c can access it.

patch below (winmerge format)

cpBBTree.patch

cpHashSet.patch

emscripten.h

Also, It’s better to use -s FORCE_ALIGNED_MEMORY=1 in your game EMCC linker options, I tend to have random crash without.

Freetype
Work, but some fonts make the library crash (My test with a 20px font made the library crash, while 8px font work, so test it beforehand)

lua
Work only if you use LUA_COMPAT_ALL in preprocessor definitions when compiling lua. Also, you must use -s FORCE_ALIGNED_MEMORY=1 in your game EMCC linker option.

libogg
Work out of the box

libvorbis
Work out of the box

libsndfile
I changed the library code to remove all references to FLAC (I only kept oggvorbis support), just exclude flac.c from your build setup and comment all references to FLAC in libsndfile code.

You also need a specific configuration, some basic type under Emscripten has a different size that what libsndfile expect, especially off_t, here’s the modified files:

config.h

sndfile.h

Finally, open the sndfile.c file, and remove the assert in the sf_open function, (should be around line 312):

assert (sizeof (sf_count_t) == 8) ;

In our case, sf_count_t size is 4, not 8, mainly because the off_t type don’t have the same size under emscripten.

protobuf-c
Work out of the box

sqlite
Work out of the box

libzip
Compile out of the box (untested in my Emscripten setup, I use the virtual file system of Emscripten, thus no need for zip packages)

zlib
Work out of the box

portaudio
The only library I ended up dropping in favour of SDL_audio. SDL_audio is included in Emscripten and use webaudio which is the best way to have sound in your html5 game at the moment. If you already use the callback interface of portaudio the port is pretty straight forward, I ended up reusing my whole mixing callback function I used for portaudio, with some minor adjustement to take into account the difference with the SDL_audio interface.

Callback function in portaudio
static int Callback(const void *input,void *output,unsigned long frameCount,const PaStreamCallbackTimeInfo* paTimeInfo,PaStreamCallbackFlags statusFlags,void *userData)

Callback function in SDL_audio
static void sdl_audio_callback(void* userData,Uint8* _stream,int _length)

The frameCount in SDL_audio can be retrieved this way :

(sf_count_t)((_length / sizeof(Sint16)) / num_channels);

(in this case, I read sound data as short values (SInt16) just use the datatype corresponding to your case)

The output pointer translate to the _stream pointer in SDL_audio.

For the other variables like input / paTimeInfo and statusFlags, you can just use the userData pointer to pass these variables around.

Another thing to consider is the threading handling. In my original code, I used atomic variables to manage multi-threading access to the sound functions. With the Emscripten version, I replace all the atomic code with SDL_LockAudio() / SDL_UnlockAudio() . Also, my existing buffer size for audio didn’t work well, so I settled on a audio buffer of 1024 bytes (so 512 bytes per channel), which is a nice compromise between audio quality / latency. I had small sound glitch under Chrome but nothing problematic.

Porting engine

As long as your engine compile under GCC, and don’t use threading, you should be safe. The biggest part is probably the rendering code if your engine is not already compatible with OpenGL ES 2.0 (WebGL work the same way than OpenGL ES). Basically, you have to remove all Fixed function pipeline code and replace it with OpenGL core 3.0 compatible code to be compatible with OpenGL ES / WebGL, You also can’t render vertices array directly and have to use VBO for everything. If you need more info about how OpenGL 3.0 work, have a look at opengl-tutorial.org

Don’t forget that if you don’t already use shaders, you will need to write some to be compatible with WebGL. About shader port, read the next section.

A note on shaders and webgl

WebGL only support GLSL shader #version 100, so you could have to port that part of your engine.

For example this code

in version 150 become this code

in version 100.

You could probably use the preprocessor to keep everything in the same shader file (with #ifdef GL_ES for GLES/WebGL specific code)
.In my case, I preferred to have separate shaders files to properly make the difference between a WebGL shader and a Desktop PC shader.

Emscripten specific gameloop

Rather than using a while() loop, with Emscripten, you just have to use this line to setup your game main loop:

emscripten_set_main_loop(renderoneframe,0,1);

where renderoneframe is your function where all your game loop code is. For more details, see the doc on Emscripten website:

emscripten_set_main_loop

Compiling the final game code

Another thing that I had to change is how I load my game DLL. In my engine, I have a module system where through dlopen / dlsym I have access to game specific functions. dlopen / dlsym isn’t supported in Emscripten, so the solution in my case was to build a .bc library file of my game DLL, reference the library header file, link it when compiling the final application, and replace my function locating code:

Desktop version
mngr->game_init_objects = (game_init_objects_t)dlsym(mngr->game_module,"game_init_objects");

Emscripten version.
mngr->game_init_objects = (game_init_objects_t)game_init_objects;

Obviously, it’s not suitable for a more complex plugin code, so you probably need to drop / refactor from the ground up any code that use plugin in native DLL form.

Here the final linker command I used :

-s USE_GLFW=3 -s TOTAL_MEMORY=67108864 -s NO_EXIT_RUNTIME=1 -s FORCE_ALIGNED_MEMORY=1

Packaging resources

Emscripten has a virtual file system available to replace the regular file system used on desktop. It work exactly the same way with fopen / fread call, so no need to change that. You only need to package your files this way:

python <path to your Emscripten directory>\emscripten\1.25.0\tools\file_packager.py emscripten_data.data --preload assets scripts locale.db save.db config.lua > emscripten_data.js

This will generate emscripten_data.data and emscripten_data.js files. The first file contains all your data, and the second file register your game files so you can access them. In this case the directories “assets” and “scripts” as well as the files “locale.db” “save.db” and “config.lua” are packaged in the emscripten_data.data file.

It’s important to run this command directly from your expected working directory. In this case, the file locale.db will be opened this way:

fopen("locale.db","rb").

If you want to open a file in the assets directory, then use:

fopen("assets/file.png","rb").

Finally, don’t forget to add your .js file in the .html file generated by Emscripten like this:

<script async type="text/javascript" src="emscripten_data.js"></script>

So your game code can find packaged files at runtime.