build(web): Add Emscripten WebAssembly target and CI workflow

Adds a web-generalsmd-sdl3-bgfx preset that cross-compiles GeneralsMD to
WebAssembly with bgfx on WebGL 2, plus a GitHub Actions job that builds it in the
Emscripten SDK container and uploads the servable page as an artifact.

Build plumbing:
- render-backend/bgfx: accept an "essl" renderer (OpenGL ES 3.0 / WebGL 2) and
  compile the shader set to the 300_es profile.
- bgfx: a cross build cannot run the shaderc it would produce, so build a host
  shaderc from the already-fetched bgfx tree, or reuse one via GGC_SHADERC_EXE.
- compilers: memory growth, pthreads and -fexceptions for every wasm target,
  since the dependencies need them too.
- sdl3/openal/gamespy: static SDL3, Emscripten's built-in OpenAL, and the Linux
  code paths for the GamespySDK.
- webfont: a browser has no system fonts, so fetch one upstream (pinned) and
  embed it, and open it directly since there is no Fontconfig either.
- Main: emit index.html/.js/.wasm and link with Asyncify plus a pre-spawned
  worker pool.
- scripts/build/web: build the minimal FFmpeg the audio and video paths need,
  which no Emscripten port provides, mirroring the Linux script.

Engine changes, all under __EMSCRIPTEN__:
- GameMain runs one iteration per animation frame instead of blocking in
  GameEngine::execute, which a browser tab cannot host.
- timeGetTime uses CLOCK_MONOTONIC; musl declares CLOCK_BOOTTIME but does not
  implement it, which left every timeGetTime-gated loop stuck at 0.
- bgfx takes the canvas selector as its window handle, and skips the
  single-threaded renderFrame call it asserts on.
- FramePacer runs uncapped because requestAnimationFrame already paces frames.
- GameLOD keeps the shell map on; its CPU benchmark cannot run in a browser.
- SDL3Main mounts IndexedDB so options and saves survive a reload.

Author: githubawn

.github/workflows/web-build.yml

@@ -0,0 +1,129 @@
+name: Web (WebAssembly) Build
+
+run-name: web build from ${{ inputs.ref || github.ref_name }}
+
+on:
+  push:
+    branches:
+      - bobtista/topic/trunk
+      # Working branches for build-infrastructure changes, so a push iterates on CI
+      # without opening a pull request first.
+      - 'ci/**'
+    paths:
+      - '.github/workflows/web-build.yml'
+      - 'CMakePresets.json'
+      - 'CMakeLists.txt'
+      - 'cmake/**'
+      - 'scripts/build/web/**'
+      - 'Core/**'
+      - 'Dependencies/**'
+      - 'GeneralsMD/**'
+  pull_request:
+    paths:
+      - '.github/workflows/web-build.yml'
+      - 'CMakePresets.json'
+      - 'CMakeLists.txt'
+      - 'cmake/**'
+      - 'scripts/build/web/**'
+      - 'Core/**'
+      - 'Dependencies/**'
+      - 'GeneralsMD/**'
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: "Branch, tag, or SHA to build"
+        required: false
+        type: string
+
+concurrency:
+  group: web-build-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  web:
+    name: web-generalsmd-sdl3-bgfx
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+    # The Emscripten SDK image carries emcc, cmake, make, node and a host g++ (needed
+    # for the host shaderc the cross build compiles its shaders with).
+    container: emscripten/emsdk:6.0.5
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          ref: ${{ inputs.ref || github.ref_name }}
+
+      - name: Mark Workspace Safe For Git
+        run: git config --global --add safe.directory "${GITHUB_WORKSPACE}"
+
+      - name: Cache FFmpeg For wasm
+        id: cache-ffmpeg-wasm
+        uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
+        with:
+          path: ${{ github.workspace }}/build/ffmpeg-wasm
+          key: ffmpeg-wasm-${{ hashFiles('scripts/build/web/build-ffmpeg-wasm.sh') }}
+
+      - name: Build FFmpeg For wasm
+        if: steps.cache-ffmpeg-wasm.outputs.cache-hit != 'true'
+        run: |
+          NPROC="$(nproc)" bash scripts/build/web/build-ffmpeg-wasm.sh "${GITHUB_WORKSPACE}/build/ffmpeg-wasm"
+
+      - name: Cache CMake Dependencies
+        uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
+        with:
+          path: |
+            build/web-generalsmd-sdl3-bgfx/_deps
+            build/web-generalsmd-sdl3-bgfx/host-shaderc
+          key: cmake-deps-web-generalsmd-sdl3-bgfx-${{ hashFiles('CMakePresets.json','cmake/**/*.cmake','**/CMakeLists.txt') }}
+          restore-keys: |
+            cmake-deps-web-generalsmd-sdl3-bgfx-
+
+      - name: Configure with CMake
+        run: |
+          FFMPEG_PREFIX="${GITHUB_WORKSPACE}/build/ffmpeg-wasm"
+          cmake --preset web-generalsmd-sdl3-bgfx \
+            -DFFMPEG_INCLUDE_DIR="${FFMPEG_PREFIX}/include" \
+            -DFFMPEG_AVCODEC_LIBRARY="${FFMPEG_PREFIX}/lib/libavcodec.a" \
+            -DFFMPEG_AVFORMAT_LIBRARY="${FFMPEG_PREFIX}/lib/libavformat.a" \
+            -DFFMPEG_AVUTIL_LIBRARY="${FFMPEG_PREFIX}/lib/libavutil.a" \
+            -DFFMPEG_SWSCALE_LIBRARY="${FFMPEG_PREFIX}/lib/libswscale.a"
+
+      - name: Build GeneralsMD
+        run: |
+          cmake --build build/web-generalsmd-sdl3-bgfx --config Release --target z_generals -j"$(nproc)"
+
+      - name: Stage
+        run: |
+          STAGE="${GITHUB_WORKSPACE}/stage-web/GeneralsZH-web"
+          mkdir -p "${STAGE}"
+          # Ninja Multi-Config appends the configuration to the output directory.
+          WEB_DIR="build/web-generalsmd-sdl3-bgfx/web"
+          if [ -d "${WEB_DIR}/Release" ]; then
+            WEB_DIR="${WEB_DIR}/Release"
+          fi
+          cp -r "${WEB_DIR}"/. "${STAGE}/"
+          cp scripts/build/web/serve.py "${STAGE}/serve.py"
+          {
+            echo "Command & Conquer Generals Zero Hour (GeneralsMD) WebAssembly build"
+            echo "preset: web-generalsmd-sdl3-bgfx (Release, wasm32)"
+            echo "ref: ${{ inputs.ref || github.ref_name }}"
+            echo "commit: $(git rev-parse HEAD)"
+            echo "built: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+            echo
+            echo "Serve this directory over HTTP with cross-origin isolation enabled"
+            echo "(COOP: same-origin, COEP: require-corp) and point serve.py at a copy"
+            echo "of the game data you own. The page will not boot from file://."
+          } > "${STAGE}/BUILD_INFO.txt"
+
+      - name: Zip
+        run: |
+          cd "${GITHUB_WORKSPACE}/stage-web/GeneralsZH-web"
+          zip -ry "${GITHUB_WORKSPACE}/GeneralsZH-web.zip" .
+
+      - name: Upload Artifact
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        with:
+          name: GeneralsZH-web
+          path: GeneralsZH-web.zip
+          retention-days: 30
+          if-no-files-found: error

CMakeLists.txt

@@ -83,6 +83,12 @@ if(SAGE_USE_OPENAL)
     include(cmake/openal.cmake)
 endif()
 
+# TheSuperHackers @build githubawn 29/07/2026 The web build has no system fonts to
+# render text with, so one is fetched and embedded in the module.
+if(EMSCRIPTEN)
+    include(cmake/webfont.cmake)
+endif()
+
 # Rendering backend selection. Must come after config.cmake (which sets
 # IS_VS6_BUILD) and before Core is added (which references the backend flag).
 include(cmake/render-backend.cmake)

CMakePresets.json

@@ -230,6 +230,30 @@
                 "GGC_BGFX_RENDERER": "vulkan"
             }
         },
+        {
+            "name": "web-generalsmd-sdl3-bgfx",
+            "inherits": "default",
+            "hidden": false,
+            "displayName": "Emscripten Web GeneralsMD SDL3 bgfx Release",
+            "binaryDir": "${sourceDir}/build/${presetName}",
+            "cacheVariables": {
+                "CMAKE_BUILD_TYPE": "Release",
+                "CMAKE_SYSTEM_NAME": "Emscripten",
+                "CMAKE_TOOLCHAIN_FILE": "$env{EMSDK}/upstream/emscripten/cmake/Modules/Platform/Emscripten.cmake",
+                "RTS_BUILD_GENERALS": "OFF",
+                "RTS_BUILD_GENERALS_TOOLS": "OFF",
+                "RTS_BUILD_ZEROHOUR": "ON",
+                "RTS_BUILD_ZEROHOUR_TOOLS": "OFF",
+                "RTS_BUILD_CORE_TOOLS": "OFF",
+                "RTS_BUILD_OPTION_FFMPEG": "ON",
+                "RTS_CRASHDUMP_ENABLE": "OFF",
+                "SAGE_USE_SDL3": "ON",
+                "SAGE_USE_OPENAL": "ON",
+                "RTS_GAMEMEMORY_ENABLE": "OFF",
+                "GGC_RENDER_BACKEND": "bgfx",
+                "GGC_BGFX_RENDERER": "essl"
+            }
+        },
         {
             "name": "win32-generalsmd-sdl3-bgfx",
             "inherits": "win32-bgfx",
@@ -362,6 +386,16 @@
                 "z_generals"
             ]
         },
+        {
+            "name": "web-generalsmd-sdl3-bgfx",
+            "configurePreset": "web-generalsmd-sdl3-bgfx",
+            "displayName": "Build Emscripten Web GeneralsMD SDL3 bgfx Release",
+            "description": "Build WebAssembly Release (bgfx + SDL3 + OpenAL + FFmpeg, GeneralsMD only)",
+            "configuration": "Release",
+            "targets": [
+                "z_generals"
+            ]
+        },
         {
             "name": "win64",
             "configurePreset": "win64",

Core/GameEngine/Source/Common/FramePacer.cpp

@@ -63,7 +63,17 @@ void FramePacer::update()
 {
 	// TheSuperHackers @bugfix xezon 05/08/2025 Re-implements the frame rate limiter
 	// with higher resolution counters to cap the frame rate more accurately to the desired limit.
+#if defined(__EMSCRIPTEN__)
+	// TheSuperHackers @performance githubawn 29/07/2026 The web main loop is driven by
+	// requestAnimationFrame, which already paces to the display refresh. Letting the
+	// busy-wait limiter run on top of that is actively harmful: the spin overruns the
+	// vsync slot so rAF only fires every other refresh (pinning the game near 30fps),
+	// and it burns the one main thread the browser needs back. Run uncapped and just
+	// measure the real frame time for logic time scaling.
+	const UnsignedInt maxFps = RenderFpsPreset::UncappedFpsValue;
+#else
 	const UnsignedInt maxFps = getActualFramesPerSecondLimit();// allowFpsLimit ? getFramesPerSecondLimit() : RenderFpsPreset::UncappedFpsValue;
+#endif
 	m_updateTime = m_frameRateLimit.wait(maxFps);
 	updatePerformanceLog();
 }

Core/Libraries/Source/WWVegas/WW3D2/BgfxBackend.cpp

@@ -168,6 +168,37 @@ int DX8Wrapper_PreserveFPU = 0;
 #include "vs_smudge_spirv.bin.h"
 #include "fs_smudge_spirv.bin.h"
 #define GGC_BGFX_SHADER(name) name##_spirv
+// TheSuperHackers @build githubawn 29/07/2026 OpenGL ES 3.0 / WebGL 2 bytecode for
+// the Emscripten build.
+#elif defined(GGC_BGFX_RENDERER_ESSL)
+#include "vs_passthrough_essl.bin.h"
+#include "fs_passthrough_essl.bin.h"
+#include "vs_uber_essl.bin.h"
+#include "vs_uber_instanced_essl.bin.h"
+#include "vs_trees_essl.bin.h"
+#include "fs_uber_essl.bin.h"
+#include "fs_uber_array_essl.bin.h"
+#include "fs_uber_frameconst_essl.bin.h"
+#include "vs_uber_array_essl.bin.h"
+#include "vs_shadow_volume_essl.bin.h"
+#include "fs_shadow_volume_essl.bin.h"
+#include "vs_shadow_apply_essl.bin.h"
+#include "fs_shadow_apply_essl.bin.h"
+#include "vs_scene_composite_essl.bin.h"
+#include "fs_scene_composite_essl.bin.h"
+#include "fs_bloom_bright_essl.bin.h"
+#include "fs_bloom_blur_essl.bin.h"
+#include "fs_ssao_essl.bin.h"
+#include "fs_copy_essl.bin.h"
+#include "vs_scene_depth_essl.bin.h"
+#include "vs_scene_depth_instanced_essl.bin.h"
+#include "fs_scene_depth_essl.bin.h"
+#include "vs_shadow_caster_essl.bin.h"
+#include "vs_shadow_caster_instanced_essl.bin.h"
+#include "fs_shadow_caster_essl.bin.h"
+#include "vs_smudge_essl.bin.h"
+#include "fs_smudge_essl.bin.h"
+#define GGC_BGFX_SHADER(name) name##_essl
 #else
 #include "vs_passthrough_dx11.bin.h"
 #include "fs_passthrough_dx11.bin.h"
@@ -1433,6 +1464,8 @@ bgfx::RendererType::Enum GetConfiguredRendererType()
     return bgfx::RendererType::Metal;
 #elif defined(GGC_BGFX_RENDERER_VULKAN)
     return bgfx::RendererType::Vulkan;
+#elif defined(GGC_BGFX_RENDERER_ESSL)
+    return bgfx::RendererType::OpenGLES;
 #else
     return bgfx::RendererType::Direct3D11;
 #endif
@@ -1444,6 +1477,14 @@ void *GetNativeWindowHandle(void *window)
     {
         return NULL;
     }
+#if defined(__EMSCRIPTEN__)
+    // TheSuperHackers @bugfix githubawn 29/07/2026 On Emscripten bgfx reads
+    // platformData.nwh as an HTML canvas CSS selector (a const char *), not as a
+    // window pointer. Passing the SDL_Window * makes document.querySelector throw on
+    // the garbage string, so bgfx never binds a canvas and the page stays black.
+    // "#canvas" is the element SDL3 creates its window on by default.
+    return (void *)"#canvas";
+#endif
 #if defined(SAGE_USE_SDL3)
 #if defined(__APPLE__)
     // TheSuperHackers @bugfix bobtista 30/04/2026 SDL_Metal_CreateView
@@ -4152,7 +4193,12 @@ void BgfxBackend::Initialize(void * hwnd, int /*width*/, int /*height*/)
     {
         // Single-threaded mode (default): this pre-init call tells bgfx::init() not to
         // create an internal render thread, so bgfx::frame() runs renderFrame() inline.
+        // TheSuperHackers @bugfix githubawn 29/07/2026 bgfx is already built
+        // single-threaded on Emscripten, where this call asserts ("This call only makes
+        // sense if used with multi-threaded renderer") and aborts before init.
+#if !defined(__EMSCRIPTEN__)
         bgfx::renderFrame();
+#endif
     }
     else
     {

Core/Libraries/Source/WWVegas/WW3D2/CMakeLists.txt

@@ -251,7 +251,13 @@ add_library(corei_ww3d2 INTERFACE)
 
 target_sources(corei_ww3d2 INTERFACE ${WW3D2_SRC})
 
-if(UNIX AND NOT APPLE)
+if(EMSCRIPTEN)
+    # TheSuperHackers @build githubawn 29/07/2026 Emscripten supplies FreeType as a
+    # port (built on demand and cached by emcc), and there is no Fontconfig for it:
+    # the web build opens an embedded font by path instead of matching one.
+    target_compile_options(corei_ww3d2 INTERFACE "-sUSE_FREETYPE=1")
+    target_link_options(corei_ww3d2 INTERFACE "-sUSE_FREETYPE=1")
+elseif(UNIX AND NOT APPLE)
     find_package(Freetype REQUIRED)
     find_package(Fontconfig REQUIRED)
     target_link_libraries(corei_ww3d2 INTERFACE

Core/Libraries/Source/WWVegas/WW3D2/render2dsentence.cpp

@@ -63,8 +63,13 @@
 #if !defined(_WIN32) && !defined(__APPLE__)
 #include <ft2build.h>
 #include FT_FREETYPE_H
+// TheSuperHackers @build githubawn 29/07/2026 Emscripten has a FreeType port but no
+// Fontconfig, and no system font directories for it to search anyway; the web build
+// opens an embedded font directly instead.
+#if !defined(__EMSCRIPTEN__)
 #include <fontconfig/fontconfig.h>
 #endif
+#endif
 
 
 ////////////////////////////////////////////////////////////////////////////////////
@@ -1796,6 +1801,19 @@ FontCharsClass::Create_GDI_Font (const char *font_name)
 		resolved_name = "Arial";
 	}
 
+#if defined(__EMSCRIPTEN__)
+	// TheSuperHackers @port githubawn 29/07/2026 A browser has no Fontconfig and no
+	// system fonts to match against, so the lookup below cannot run and every string
+	// would render blank. Use the font embedded in the module instead (fetched and
+	// embedded by cmake/webfont.cmake), picking the bold face by name.
+	const char *embedded_font = IsBold ? "/fonts/DejaVuSans-Bold.ttf" : "/fonts/DejaVuSans.ttf";
+	FT_Error face_error = FT_New_Face(FTLibrary, embedded_font, 0, &FTFace);
+	if (face_error != 0) {
+		FT_Done_FreeType(FTLibrary);
+		FTLibrary = nullptr;
+		return false;
+	}
+#else
 	FcConfig *config = FcInitLoadConfigAndFonts();
 	FcPattern *pattern = config != nullptr
 		? FcNameParse(reinterpret_cast<const FcChar8 *>(resolved_name))
@@ -1839,6 +1857,7 @@ FontCharsClass::Create_GDI_Font (const char *font_name)
 		FTLibrary = nullptr;
 		return false;
 	}
+#endif // __EMSCRIPTEN__
 
 	int font_height = max(1, static_cast<int>(FT_MulDiv(PointSize, 96, 72)));
 	if (FT_Set_Pixel_Sizes(FTFace, 0, static_cast<FT_UInt>(font_height)) != 0) {

Dependencies/Utility/Utility/endian_compat.h

@@ -25,7 +25,7 @@
 #include <Utility/stdint_adapter.h>
 
 
-#if defined(__linux__) || defined(__CYGWIN__)
+#if defined(__linux__) || defined(__CYGWIN__) || defined(__EMSCRIPTEN__)
 #include <endian.h>
 
 #elif defined(__APPLE__)
@@ -116,7 +116,7 @@
 
 
 // Endian helper function data types
-#if defined(__linux__) || defined(__CYGWIN__)
+#if defined(__linux__) || defined(__CYGWIN__) || defined(__EMSCRIPTEN__)
 typedef uint16_t SwapType16;
 typedef uint32_t SwapType32;
 typedef uint64_t SwapType64;

Dependencies/Utility/Utility/time_compat.h

@@ -28,7 +28,15 @@ static inline MMRESULT timeEndPeriod(int) { return TIMERR_NOERROR; }
 inline unsigned int timeGetTime()
 {
   struct timespec ts;
-#if defined(CLOCK_BOOTTIME)
+#if defined(__EMSCRIPTEN__)
+  // TheSuperHackers @bugfix githubawn 29/07/2026 Emscripten's musl declares
+  // CLOCK_BOOTTIME but does not implement it, so clock_gettime() fails and leaves ts
+  // zeroed and timeGetTime() always returns 0. Every timeGetTime-gated loop then stops
+  // making progress - Shell::update's 30Hz gate never opens, so menu update callbacks
+  // never run and menus draw but never navigate. CLOCK_MONOTONIC is supported, and is
+  // what GetTickCount() below already uses.
+  clock_gettime(CLOCK_MONOTONIC, &ts);
+#elif defined(CLOCK_BOOTTIME)
   clock_gettime(CLOCK_BOOTTIME, &ts);
 #else
   clock_gettime(CLOCK_MONOTONIC, &ts);

GeneralsMD/Code/GameEngine/Source/Common/GameLOD.cpp

@@ -618,9 +618,15 @@ void GameLODManager::applyStaticLODLevel(StaticGameLODLevel level)
 		TheWritableGlobalData->m_useFpsLimit = lodInfo->m_useFpsLimit;
 		TheWritableGlobalData->m_useTrees = requestedTrees;
 
+#if !defined(__EMSCRIPTEN__)
+		// TheSuperHackers @bugfix githubawn 29/07/2026 The CPU-MHz / memory benchmark
+		// this reads cannot run in a browser, so it always reports the machine as
+		// low-end and turned the 3D shell map off - the main menu came up with a black
+		// background instead. Leave the shell map enabled on the web build.
 		if (!m_memPassed || isReallyLowMHz()) {
 			TheWritableGlobalData->m_shellMapOn = false;
 		}
+#endif
 	}
 
 	if (TheTerrainVisual)