I wrote a game in plain C with a custom engine (bgfx, SDL2, miniaudio, cimgui) and recently ported it to web via Emscripten. Its live on itchio now. Here’s everything non-obvious that I ran into, hopefully saves someone some pain.

0. Had to go back to Visual Studio. Ugh.

I use RemedyBG as my daily debugger and its great, but it doesnt support 32-bit processes. Since WASM is 32-bit, I needed a 32-bit native build to reproduce bugs locally, which meant firing up Visual Studio again.

Turns out you don’t need a solution file. Just run:

devenv build\main.exe

and before you build, add vcvars32 to your build process

call "C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvars32.bat"

On VS, just Hit F5 or F11 and it runs the exe directly. No sln file needed, works fine for stepping through code and catching crashes. Not ideal but got the job done.

1. Web is 32-bit. Your 64-bit structs will break.

This was the root cause of most of my bugs. WASM is 32-bit address space, pointers are 4 bytes not 8. I was serializing asset structs directly to disk (pak file) that had raw pointers in them:

typedef struct AssetSprite {
    u32 width, height;
    u8* dataBytes;  // 8 bytes on 64-bit, 4 bytes on WASM
    i32 dataSize;
} AssetSprite;

When I packed assets on 64-bit Windows and loaded them on WASM, the struct layout was completely different. sizeof(Assets) was 26328 on native and 25556 on web. Every field after the first pointer was at the wrong offset, so all texture and shader data came out as garbage.

In hindsight this is probably obvious to anyone who builds cross platform regularly, but I havent built 32-bit in years so I tripped on the pointer size thing.

Fix: I separated runtime data from baking data entirely. Instead of a pointer living inside the asset struct, I now have a flat array on the side:

AssetDataBytes assetData[TOTAL_ASSET_COUNT];
i32 assetDataId;

typedef struct AssetDataBytes {
    u8* data;
    i32 size;
} AssetDataBytes;

Every time I add a new asset during baking, just bump assetDataId and write the bytes there. The serialized asset struct has no pointers at all, so layout is identical on 32 and 64-bit. Packer is single threaded and still finishes under 3 seconds for the whole game, good enough for my use case since asset count is relatively small.

2. Debug in 32-bit native, not the browser

This was the biggest productivity unlock honestly. Since 32-bit native has the same struct sizes as WASM, bugs that only appeared on web also appeared on 32-bit native, where I had real breakpoints, memory watch, and call stacks.

For actually hunting the bugs I used a combination of /fsanitize=address when compiling plus data breakpoints. Trigger the bug, ASan will catch the bad access. Data breakpoint would also tells you exactly what wrote to that address. Makes what would be a multi hour hunt into something you can solve pretty quickly. Dont try to debug WASM crashes from the browser console alone since its painful and slow.

3. A bug that was silently correct on 64-bit

typedef struct ThingHandle {
    i32 id;
    i32 generation;
} ThingHandle;

// wrong
game->boardPieces = swAlloc(sizeof(ThingHandle*) * row * column);

// correct
game->boardPieces = swAlloc(sizeof(ThingHandle) * row * column);

On 64-bit, sizeof(ThingHandle*) is 8, which happens to be the same as sizeof(ThingHandle). So the wrong code allocated exactly the right amount of memory by coincidence and worked fine for a while. On 32-bit WASM, sizeof(ThingHandle*) is 4, so it allocated half the memory it needed and corrupted whatever came after it. Pretty classic mixup, just hidden for a long time by 64-bit making them accidentally equal.

4. OpenGL ES (WebGL) is way stricter than Direct3D

bgfx uses Direct3D on Windows and OpenGL ES on web. A bunch of things I got away with on D3D broke hard on WebGL:

Vertex layout renderer type: I was passing BGFX_RENDERER_TYPE_NOOP to bgfx_vertex_layout_begin. Works on D3D, broken on OpenGL because it cant assign correct attribute locations. Use bgfx_get_renderer_type() instead.

Component count mismatch: I had COLOR1 declared as 2 components in the layout but the shader used vec4. D3D ignores the mismatch. OpenGL ES throws a fatal every frame. Component counts must exactly match what the shader declares.

Framebuffer Y flip - OpenGL has Y=0 at the bottom, D3D has Y=0 at the top. My fullscreen blit was upside down on web. Fixed by flipping UV V coordinates in the final render target texture blit.

5. Shaders need recompiling for GLSL ES

bgfx’s shaderc compiles for specific backends. My shaders were HLSL compiled for DirectX. On web I needed GLSL ES, profile flag changes from -p s_5_0 to -p 300_es.

Two things that tripped me up:

• lerp() is HLSL only. GLSL uses mix(). bgfx’s bgfx_shader.sh already defines mix as a cross platform macro so just use that everywhere and both platforms work.
• GLSL ES is strict about integer vs float. Passing 0 or 1 to a float parameter is a compile error. Has to be 0.0 and 1.0.

6. Web Audio autoplay + a weird Emscripten exports issue

Google has implemented a policy in their browsers that prevent automatic media output without first receiving some kind of user input. Miniaudio handles this internally by registering click and touchend listeners that resume the AudioContext automatically. I spend too much time trying to make miniaudio web build works messing around with a lot of it’s flags AUDIO_WORKLET, WASM_WORKERS, ASYNCIFY. Even trying to make a different initialization path between web & native, the web init after the first touch, but it still not working, there’s still an error throws on the js console when the AudioContext initialized.

Turns out newer versions of Emscripten seem to remove some runtime exports by default. miniaudio needs HEAPF32 to be available from JS side and it wasnt. Had to explicitly add it:

-s EXPORTED_RUNTIME_METHODS="['ccall','cwrap','HEAPF32']"

Not sure if this is a newer Emscripten behavior or a combination of my flags, couldn’t find anything on google about it, might save someone an hour of head scratching. All things considered, miniaudio really get the job done, nothing need to be initialized differently between native and web

Final thoughts

Genuinely happy with how it turned out, I spent a weekend on this port and honestly expected it to take longer. Writing a custom C engine, porting it to web, having the game load fast and play instantly with no Unity or Godot baggage, that feels really good.

The Emscripten toolchain is solid. Most of the pain came from things that worked by accident on Windows that the web holds you accountable for. Once you know what to look for, fixing them is pretty straightforward.

Game is live https://zhongda8.itch.io/matchmorphosis

And you can wishlist it https://store.steampowered.com/app/4131100/Match_Morphosis

Thanks for reading!