DEV Community: Virtastic

Porting FreeCAD to wasm64: what broke after the compile succeeded

Virtastic — Mon, 21 Sep 2026 16:18:17 +0000

freecad-web 1.0 is FreeCAD 1.1.3 compiled to wasm64-emscripten and running in your browser: Qt 6.11, OCCT 7.8.1, Coin3D 4.0.3, VTK 9.3.1, CPython 3.13.3, PySide6, numpy, matplotlib, IfcOpenShell, with Gmsh and CalculiX as separate wasm modules.

Getting it to compile and link took a few weeks. Getting it to behave like desktop FreeCAD took the other two and a half months, and almost none of that went into compile errors. It went into things that compiled cleanly, linked cleanly, passed a scripted test, and did nothing when a person clicked. This post is about those.

One rule came out of it and now sits at the top of the project's working agreements: a scripted test through the Python bridge is a weaker claim than a real mouse click, and a return value can be the failure. Most of what follows is that rule being learned the expensive way. Every number here is from BUILD-WEH.md or MANUAL-QA.md in the repository, and the commit hashes are real.

The shape of the thing

185 MB of wasm, 293 MB of preloaded file system, 1.4 MB of JS glue. Wasm exceptions in the new try_table encoding, JSPI for suspending into JavaScript, pthreads with a pool of 16, a heap that starts at 1 GiB and can grow to 16 GiB, which is where V8 caps 64-bit memory. Coin3D is a fixed-function OpenGL renderer, so it runs on emscripten's legacy GL emulation on top of WebGL 2. Nothing is dynamically loaded: every Python extension is in the inittab and on the link line, and if it is missing from either it builds fine and fails to import.

The server is nginx serving static files with brotli. The browser fetches about 115 MB on the first visit and nothing on the second. That second part took longer than it should have.

1. Only promising exports may suspend

JSPI lets a wasm export be marked promising: calls into it can suspend on a JavaScript promise and resume later. FreeCAD needs this constantly, because a modal dialog is a nested event loop and a nested event loop in a browser is a suspension.

Every dialog opened when driven from Python through our promising export. Not one opened from a real mouse click. The gate said "0 page errors" and the harness reported success, because the harness was driving Python.

The mechanism, once we stopped theorising and read qstdweb.cpp:743-751: Qt's DOM event listener enters wasm through an embind call that is not a promising export. QDialog::exec called from that path tried to suspend and threw SuspendError: trying to suspend without WebAssembly.promising, which Qt swallowed. The identical C++ from a promising path was fine.

The fix is one promising export, fcweb_dispatch_event, and a drop-in replacement for the listener class that routes real DOM events through it. Drag and drop in the tree had the same disease (QDrag::exec) and the same cure.

2. JSPI switches the wasm stack, not the C stack

When a promising call suspends, JSPI saves the wasm execution stack. It knows nothing about the shadow stack that C code keeps in linear memory for locals whose address is taken. The shadow stack pointer is a global, and a second promising activation that starts while the first is suspended happily runs on top of the first activation's frames.

The symptom: a Gmsh mesh from the FEM workbench wrote its result correctly and then CPython died with Fatal Python error: Executing a cache. The trace showed Qt's main loop had resumed 15 times inside one gmsh call, each time over the suspended Python call's frames.

The fix (466d90c) gives every promising export a private malloc'd stack, from a pool, for the duration of the call.

3. The keyboard never entered Qt

Typing into a text field worked perfectly. Delete, Ctrl+Z, Escape and every shortcut did nothing, silently.

Qt for WebAssembly focuses a hidden DOM input element only when a text widget has focus. With anything else focused, document.activeElement is the body, and keydown never reaches Qt at all. This was found with an application-wide Qt event filter that logged every key event: it logged the letters and nothing else.

The fix forwards trusted key events to Qt's canvas, with isTrusted as the loop guard and skipped when a text field has focus, so that typing abc123 still yields exactly abc123. The test is per focus target, with real key events, because a bridge-driven test cannot see this.

4. The compositor recorded the frame and never presented it

The threaded Qt build showed a black viewport. Single-threaded, identical C++, showed the model. Ten theories were written down and disproved before the measurement that mattered: instrument the GL glue and count draws and blits that reach the default framebuffer. On the threaded build, zero. Ever. Qt recorded the compose into an offscreen target and the present pass never happened.

A bisect on FreeCAD 1.0.0 with nothing but -feature-thread toggled turned 9,485 distinct colours in the viewport into one. The fix (691e7bd) has the page perform the final present pass itself each animation frame. Threading stays on.

Closely related: Qt's RHI draws on Coin's GL context, and emscripten's emulation state is global across contexts. Every external GL state reset needs a symmetric reassert, or Coin's lazy element cache decides nothing changed and skips it. "Missing" geometry was unoccluded geometry.

5. The 2 MB ceiling in immediate mode

An 18 MB STL threw from getTempVertexBuffer. Coin had emitted one glBegin of 153,600 vertices, 4.3 MB of them, against emscripten's GL.MAX_TEMP_BUFFER_SIZE of 2 MB. Before the throw, typed-array stores past the end were being silently discarded, so smaller meshes were being truncated without anyone noticing.

The buffer now grows on demand (8a2f343). The obvious alternative, switching Coin to VBOs, was measured and rejected: a 626-solid STEP file never became responsive within 600 seconds with VBOs on, because VBO-on routed Mesh nodes onto emulation code that had never run.

6. Display lists had never worked

glGenLists returns 0 in emscripten's legacy GL emulation. Coin treats 0 as "no display list" and re-traverses the node every frame. It had been doing that since the first link. A profile of a BIM drag showed 63% of the frame in scene traversal.

The fix (c741277) records every GL import between glNewList and glEndList in JS, snapshots the client-side arrays, and replays on glCallList. 1,769 replayed operations take 9.6 ms; 7 pixels of 2.6 million differ from the direct path. BIMExample went from 39.6 to 50.3 fps.

7. Qt timers starve, and Chrome clamps the rest to 4 ms

Two timer problems, one after the other.

First: once any promising activation calls processEvents, it overwrites the single resume slot the main loop was parked on, and onTimer is a no-op under asyncify. A 1 second QTimer ticked five times and died. The page now pumps Qt once per native timer wake.

Second, after that: Chrome clamps nested setTimeout(0) to 4 ms, and Qt parks on one per processEvents. The main thread was 61% idle in a profile while frames took 16.7 ms. Zero-delay Qt timers moved to a MessageChannel (273a785), and BIMExample went to 6.9 ms per frame. Desktop is 13.3 on the same machine.

8. Python shipped with no bytecode

1,486 .py files under Mod, 0 .pyc. Every boot compiled Draft from source: 1.6 seconds for import Draft against 2 ms warm. The packager stamps files with the unpack time, so timestamp-validated bytecode never validates. Unchecked-hash bytecode compiled between install and link (13cc5f3) took the import to 0.36 s and a 42 MB assembly open from 71 s to 28 s.

9. wasm64 was mostly fine, except where it was not

Moving from wasm32 to wasm64 grew the binary 12.7% and removed the memory ceiling. Three things bit:

Pointers are BigInts. The post-link GL patches used >> 2 to turn a byte pointer into a heap index; BigInt will not shift by a Number, so it becomes / 4. Only 4 of the 48 patch anchors carry a heap index, but each was a silent wrong answer until found.
glShaderSource reads its GLint *length array at pointer width (d3aa482). Correct by accident on wasm32, every Qt shader arrived truncated on wasm64 with "Missing main()". The entire widget layer vanished as soon as a 3D view existed, while Coin, which is fixed-function and has no shaders, kept drawing. Every gate that photographed the viewport passed. The gate now scans for Qt shader compile failures.
IfcOpenShell's schema registry took the renderer to 8 GB and Chrome killed it (5eadc88). Not the heap and not TurboFan: V8 lazily compiling three generated functions of 1.0 to 1.4 MB each, in a 116 MB code section with pointers twice as wide. -Oz -fno-inline on the generated schema files only.

10. The engine was never cached

Every visit downloaded the engine again: 113 MB and two to three minutes, immutable and a one-year max-age notwithstanding. Chrome's disk cache will not retain entries of that size. Cache Storage will, and reads a 152 MB entry back in 111 ms. Cold boot went from 171 s to 23 s and a return visit from 115 s to 8 s with 0 bytes fetched.

A related trap: the JS, wasm and data files are one artifact and are served immutable-for-a-year with md5-stamped names. A returning visitor with a cached JS and a fresh wasm gets a dead boot, and only returning visitors do, which is why one gate deliberately reuses a browser profile.

11. Things that only a person can see

Two classes of defect that no harness catches, and that now live on the manual QA pass:

A modal sitting mid-canvas with a console reporting zero errors. The stale-cache boot failure was exactly this. When a harness says everything is fine and nothing works, take a screenshot.
Chromium's native file picker, which no script can answer, and a native drag that Chrome refuses to begin from synthesised input. The drop pipeline is verified by simulation; only a hand proves the gesture starts.

What we changed upstream, and what we did not

Every delta lives as a patch in patches/: 8,506 lines across 18 files, 7,162 of them against FreeCAD itself. The rule was to adapt upstream code rather than replace it. A guard on sys.platform == "emscripten" around a subprocess call keeps the feature and removes the crash; a reimplementation of the feature is a parity bug waiting to diverge. The blocking dialog module exists so that a Python-triggered dialog still returns the user's real choice rather than a default.

Things the desktop does that this build knowingly does not, all on the front page: Firefox and Safari (no JSPI yet), multi-threaded CalculiX, and an OpenSCAD binary for CSG evaluation.

The numbers, for the record

On an idle machine with an RTX 4080, dev tree of 2026-09-13: EngineBlock opens in 0.3 s and drags at 37.8 fps; BIMExample opens in 7.1 s and drags at 58.2 fps; the 42 MB a2plus assembly opens in 20.2 s and drags at 25.5 fps. Against desktop FreeCAD 1.1.3 on the same machine, the web build is faster on Draft-heavy files (ArchDetail by 5 to 7 times), 2 to 5 times behind on BIMExample, and within 2x on open times everywhere. The per-frame floor is about 20 ms.

Everything above, with the measurement that found it and the upstream line where the mechanism lives, is in BUILD-WEH.md. The harnesses that produced the numbers are in scratchpad/. If you are porting a large Qt or Python application to wasm and hit something that looks like one of these, that file is probably the fastest hour you will spend.

The release post has what the result looks like from the user's side. Try it or read the source.

Originally published at virtastic.app.

Jagged Alliance 2, running in your browser

Virtastic — Mon, 10 Aug 2026 15:39:50 +0000

If you own Jagged Alliance 2, you can now play it in a browser. Point
ja2.virtastic.app at the folder your copy already lives in and it runs: the full
campaign, full tactical combat, mouse and keyboard, sound intact. Nothing to install, and your
game files never leave your machine.

What it's built on

This is Stracciatella, the open-source
reimplementation of the Jagged Alliance 2 engine. The same relationship as our Morrowind port to
OpenMW: a community project already rebuilt the engine from scratch, and our job was getting that
engine to run in a browser instead of on a desktop. Full credit to the Stracciatella team. We
recompiled their engine to WebAssembly; the engine itself is theirs.

The launcher. You point it at the Data folder your copy already lives in, and the files are read locally.

What it took

The shape of the problem was familiar from OpenMW: an engine written for a desktop event loop,
a desktop filesystem, and desktop audio, none of which a browser gives you for free. Sound became
Web Audio. The UI and mouse-driven tactical combat run exactly as they do on desktop, translated
onto browser input events. And like OpenMW, it's a "bring your own data" port: Jagged Alliance 2's
game data is commercial, so the launcher points at your own legally-owned copy and reads it
straight off disk. Nothing is uploaded anywhere.

A.I.M., the in-game mercenary hiring site, complete with its 1999 web design. All of it runs client-side.

One detail worth calling out: it keeps running in a background tab. Browsers throttle inactive
tabs hard, which is normally the right call, and normally invisible unless your game depends on a
turn timer or an AI that needs to keep thinking while you've alt-tabbed away. Jagged Alliance 2
does. The port accounts for that, so switching tabs mid-mission doesn't leave the game stuck or
desynced when you come back.

The original title screen, unchanged, in a browser.

Try it

Play it in your browser if you own the game, read the source on
GitHub, and if you hit a bug, tell us or drop
it in the Discord.

This is our second full release after OpenMW.
More are on the way.

OpenMW in the browser: porting a 3D engine

Virtastic — Sat, 25 Jul 2026 23:27:17 +0000

Games are the hardest test of desktop-to-web conversion. A real-time 3D engine touches everything at
once: the GPU, the audio device, threads, the filesystem, input. If the port stutters anywhere, you see
it instantly. That is exactly why we picked OpenMW, the open-source reimplementation of The Elder
Scrolls III: Morrowind, as one of our proof ports.

It runs in a browser tab today at morrowind.virtastic.app, and it is our most polished
conversion. Here is how the port works, the parts that fought back, and what a game engine proves about
modernizing serious software.

How it was done

OpenMW is a heavyweight C++ engine with a heavyweight dependency stack: OpenSceneGraph for rendering,
Bullet physics, MyGUI, FFmpeg for audio and video decoding, Boost, Lua, Recast navigation. All of it is
cross-compiled to WebAssembly with Emscripten, with threads and native-speed exceptions enabled.

Exception handling is worth a footnote of its own. The engine, every dependency, and the final link all
have to agree on the same exception model, and when they disagree you get link errors that point at
nothing useful. Everything here is built against native WebAssembly exceptions. Getting that consistent
across the whole tree cost real time before a single frame rendered.

The interesting engineering is at the seams, where desktop assumptions meet browser reality:

OpenGL became WebGL2. The renderer's shaders were ported to GLES/WebGL2 semantics, and character animation moved to GPU skinning. OpenSceneGraph was the single hardest dependency in the stack and it earned its own patch series.
The filesystem became a streaming virtual filesystem. A desktop engine assumes gigabytes of assets sitting on disk. In the browser, assets stream in on demand and the Cache API keeps them local for the next session, so the second visit starts fast and the first one doesn't demand a giant download up front.
State became persistent browser storage. Saves, settings and keybindings live in IndexedDB, synced in the background and on tab close. Close the browser mid-quest and tomorrow the tab reopens where you left it.
Desktop-only APIs got stubbed at the boundary. X11 and friends are no-ops behind the same kind of guarded patches we use in every port. Upstream code untouched, browser divergences small and reviewable.

GPU skinning, per-pixel lighting and real-time shadows, all running client-side in a tab.

The bugs that only exist on the web

Most of what broke was WebGL2 and OpenGL ES being far stricter than desktop GL, while OpenSceneGraph
quietly assumed desktop behaviour underneath.

The world was too dark. Interiors and exteriors came out badly underlit, because of how the sun and
lighting parameters were reaching the shaders. Flattening them into plain uniforms the GLES path
actually accepts brought the world back to proper brightness.

Equipping a weapon froze the game. Native OpenMW hands work to background threads. Block the main
thread in a browser and you don't stall a worker, you freeze the entire tab. A work queue was waiting on
a result that could never arrive, so that path now runs inline.

Shadows crawled. Shadows shimmered and swam as the camera turned. It looked like a precision problem
and it wasn't: the cause was the cascaded shadow map's cascade transitions. We collapsed to a single
cascade with a 16384 map, which keeps the shadow texel grid locked in world space by construction.

We verified that mechanically rather than by eye. An instrumented 360-degree rotation measured the texel
size per cascade at every yaw and it never moved: 0.000244 at the near cascade, 0.000488 and 0.000977
further out, constant through a full turn. A grid that never shifts relative to the world cannot crawl.

Stable shadows and real-time water reflections, the two things that fought hardest.

Faces turned into cones. Morph-based facial animation was disabled on the web because it fired
spikes out of characters' heads. The cause was how the morph geometry's vertex arrays were laid out.
Putting all of them on one dedicated vertex buffer, the way the skinned geometry already did, fixed it,
and faces went back on.

Post-processing wedged the shader compiler. The modern post stack, bloom included, refused to link.
Several separate GLES incompatibilities were stacked on top of each other: a fragment output binding call
that WebGL rejects and that was silently wedging program linking, struct uniforms that had to be
flattened by hand, float render targets that had to be requested explicitly, and, in the bloom shader,
a file-scope global initialised from a runtime value. That last one is illegal in GLSL ES and killed the
link every time.

Antialiasing: the fix we were proud of, and then mostly couldn't use

This is the most honest story in the port, so it gets its own section.

We got hardware MSAA working, and it was a real fight. Two stacked bugs in OpenSceneGraph's GLES path
had it broken. First, the per-colour-attachment resolve blit was wrapped in a preprocessor guard that
compiled it out entirely on GLES, while OpenMW was attaching its resolve target in a way that path never
handled. Second, even after that, the blit function OSG wanted to call is a null pointer under
Emscripten, so the whole resolve had been gated off. We folded the colour resolve into the main blit and
called the WebGL2 blit directly. MSAA rendered clean and antialiased at 60fps with a clean GL error
state. Verified.

And then we mostly couldn't use it. MSAA falls apart under post-processing on WebGL2, and the modern
pipeline runs post-processing by default. So the antialiasing you actually get from the Options dropdown
is SSAA: the scene renders at a higher resolution and scales back down. It is cheap on the GPU and hungry
on memory, hungry enough that at full retina resolution the supersampled buffers ran the tab out of
memory during boot until we capped the effective pixel count. The dropdown offers Off, 1.5x and 2x, and
it stays under the ceiling.

Both paths are genuinely in there. MSAA works and is verified. SSAA is what most people will actually
run, because it survives the pipeline we ship.

Then we didn't stop at "it runs"

Being that deep in the renderer already, we spent the remaining headroom making it look better than it
did in 2002:

Radial and distance fog with sky blending, so the horizon reads as atmosphere instead of a hard wall.
Per-pixel lighting across the world, in place of the original per-vertex lighting.
Alpha-to-coverage on foliage, so leaves have clean edges instead of harsh cutouts.
Anisotropic filtering up to 16x, so ground textures stay sharp at grazing angles.
Real-time water reflections. Reflection buffers cannot be multisampled on GLES, so rather than ship a jagged reflection we blur it in the shader.

Distance fog, sky blending and shader-blurred water reflections on the Bitter Coast.

Where it landed

Steady 60fps across the world, including a full walk through Balmora with no hitching. The engine is CPU
bound on draw submission rather than GPU bound, which is a good problem: it means the headroom went into
the rendering work above. Memory holds at about 1.5GB in Balmora, the densest town in the game, and does
not grow. Saves persist, mods load, gamepads work through the same SDL input path the native build uses.

One honest limitation: this is a Chromium target. We are not chasing Firefox or Safari parity right now.

"Bring your own data", the pattern that matters most

Morrowind's game data is commercial, so the port ships a free example world plus a launcher that lets you
point the engine at your own copy of the game using the browser's File System Access API. The engine
reads your files directly from your disk.

Two doors: a free example world, or your own install read straight off disk. Nothing uploads.

Read that again from a business angle: a browser application working against local, sensitive data, with
nothing uploaded anywhere. The compute runs client-side and the data never leaves the machine. That is
precisely how a browser-based engineering or analysis tool can handle confidential project files. You get
the web app's convenience without the "our files on someone's cloud" objection.

What the browser version does better

Distribution is a link. No installer, no GPU-driver roulette, no "works on my machine." Send a URL and it runs, including on machines where users cannot install anything.
Updates are invisible. Engine fixes land for every player on next load. Nobody is stranded on an old build.
Progress follows the browser profile. Saves survive without a launcher account or manual save management.

Why a game proves the business case

Nobody's line-of-business app is harder on a browser than a real-time 3D engine. If WebGL2 rendering,
physics, streamed assets, audio and persistent state hold up in a tab, a forms-and-documents desktop
application is comfortably within reach. A Qt-based professional tool sits in between, which is exactly
where our FreeCAD work picked up the same patterns: the
shader work, the virtual filesystem, the persistence layer. That one is still in preview. This one you
can play right now.

Try it

Play it in your browser (desktop Chromium works best), read the source on
GitHub, and if you have a desktop application you'd like to see running in a tab,
book a meeting.