Vinicius Cole

Linking is not running: a C++ OpenGL game in the browser

2026-11-01T00:00:00Z

The side-scrolling game on this site was a Computer Graphics assignment: C++, immediate-mode OpenGL, GLUT, an arena read from an SVG file. Porting it was the opposite of the tic-tac-toe port. There, a 1.4 MB emulator runs a 3 KB DOS program. Here there is no emulator. The 181,051 bytes of jogo.wasm are my C++, compiled by Emscripten.

Getting it to compile took one command:

em++ -std=c++11 -O2 main.cpp arena.cpp tinyxml2.cpp character.cpp \
     hero.cpp enemy.cpp shot.cpp \
     -sLEGACY_GL_EMULATION=1 -lGL -lglut \
     --preload-file arena_teste.svg -o jogo.js

It linked clean. I almost wrote down “immediate-mode OpenGL works”. Then I opened it in a browser, and it died on the first frame:

Aborted(unsupported immediate mode 9)

Mode 9 is GL_POLYGON, which the game uses to draw every character’s head. Emscripten’s emulation of old-style OpenGL doesn’t implement it. Swapping in GL_TRIANGLE_FAN draws the same thing for a convex shape, so it’s a one-word patch.

The patch didn’t bother me. What bothered me was that the compiler, the linker and a quick look at the output sizes had all said yes to a program that couldn’t draw a single frame. Nothing short of actually running it would have caught that.

So I built a bench: a script that opens the game in a real Chromium (headless, inside the Playwright Docker image), presses keys and clicks the mouse, and checks what happens on screen. Most of what I learned from this port came from that bench being wrong.

You can’t read a WebGL canvas

The first thing the bench needs is “did anything draw?”. The obvious answer is to read the canvas pixels. That returns solid black, every time, because WebGL throws the drawing buffer away once the frame is on screen unless you ask it not to.

What works is going the long way round. Take a Playwright screenshot, load it into an <img>, draw that onto a 2D canvas and call getImageData. Every measurement in the bench goes through that path.

A test that passes with the keyboard unplugged

The first version of “pressing D moves the player” compared two screenshots of the whole canvas, one before the key and one after, and passed if they were different.

They are always different. The arena has seven enemies that walk and shoot on their own from the first frame. The picture changes between any two moments, with or without a keyboard. The test would have passed with input completely broken, which is worse than not having it, since everything after it trusted it.

So the bench measures the thing that should move. The hero is the only green on screen, so the bench finds the horizontal centre of the green pixels and asserts that D pushes it more than 20 px right and A pulls it back. It has to be measured near the spawn point, too: the camera follows the hero, so after a few steps the hero stays centred and the on-screen movement shrinks to almost nothing.

Jumping was a timing problem. A quick tap of W lifts the hero 21 px and lands in under 90 ms. My first measurement ran 250 ms after releasing the key, saw the hero on the ground and reported a failure that wasn’t one. Holding W for 900 ms reaches 147 px. The bench now takes three samples right after release and keeps the highest point.

`exit(0)` doesn’t exit

The original game quits on ESC with exit(0). On a desktop that’s fine. On a web page there is nowhere to quit to, so the port turns ESC into a no-op. The bench checked that by pressing ESC and confirming the hero was still visible.

That check was useless, and I only found out by breaking the guard on purpose and rebuilding. With Emscripten’s -sEXIT_RUNTIME=0, exit(0) doesn’t stop anything. It throws an uncaught ExitStatus exception inside the key handler, the page logs an error, and the requestAnimationFrame loop that was already scheduled keeps going. The hero never left the screen, so my check was testing the one thing the regression doesn’t break.

The assertion that catches the regression counts page errors before and after ESC. “The hero can still walk after ESC” stays in as a second line of defence, in case the build ever switches to EXIT_RUNTIME=1.

This became the rule for the whole bench. Every assertion had to be shown to fail: put the bug back, watch the check go red, then restore it. For the GL_POLYGON fix that meant editing the patch back to glBegin(GL_POLYGON), rebuilding, and seeing the bench catch the abort. One check didn’t survive the rule at all: “holding W jumps higher than tapping” compared against Math.min of a list that could be empty. Math.min() of nothing is Infinity, so any height passed.

What the game did to the page

GLUT on Emscripten listens to keydown and keyup on the whole window and calls preventDefault on Tab, Enter and Space. The game doesn’t use any of them. Once someone clicked Play, keyboard users were stuck on the canvas. Tab couldn’t reach the footer or the theme button, or even the “play again” button on the game’s own end screen. A capturing listener on the window, registered before the game module loads, now grabs those three keys before GLUT sees them.

That end screen was broken too. GLUT’s bitmap fonts don’t exist in Emscripten, so “You won” and “You lost” are HTML now, shown over the canvas. The C++ calls into the page on every frame while the game is over. When R restarts the game it just stops calling, and nothing told the page to hide the message. The overlay stayed on top of a running game and swallowed every click. Now restartGame() tells the page when play starts again.

The last one only showed up on the real site. The bench served the three build files from one flat directory. On the site, the page lives at /projects/... and the game at /demos/.... Emscripten’s loader looks for jogo.data (the packed SVG arena) relative to the page, not to jogo.js, so on the real site it was a 404 every time. A locateFile option in the loader fixed it, and the bench gained a second mode that loads the real built page, because the flat version can’t see this kind of bug by design.

Three patches, and a lot of bench

The game itself barely changed: three small patches on a pinned commit of the original repo, and the assignment’s own make still builds the desktop version with the original GLUT text.

I went in expecting OpenGL to be the hard part. It was the bench.

Teaching a C program to show its work

2026-11-01T00:00:00Z

The route project started as a 2023 assignment I did with two classmates: read a map, find the fastest route, and replan when traffic changes mid-trip. It’s plain C. You give it a file, and it writes back three lines: the path, the kilometres and the time.

That’s a fine answer for a grader and a useless one for a web page. I wanted readers to watch Dijkstra open and close nodes, see the car leave, see a road jam and the car change its mind. The C knew all of that while it ran. It just never said any of it out loud.

Rewriting the algorithm in JavaScript would have turned the C into a link to the repo, and pre-recorded animations would have meant nobody could cause their own traffic jam. So the C had to learn to narrate.

Hooks that cost nothing when nobody listens

The C got a struct of function pointers, one per event, all NULL by default:

typedef struct {
  void (*pop)(int node, double time);
  void (*relax)(int from, int to, double new_time);
  void (*plan)(const int *path, int length, double eta);
  void (*move)(int from, int to, double t0, double t1);
  /* ...update, replan, unreachable, done */
} TraceHooks;

dijkstra and the replanning loop call each one only if it’s set. The original command-line program never sets them, so for it the change is a handful of NULL checks.

Before moving a single line, I saved the CLI’s output for a few test maps as the expected result. Any change after that had to reproduce those files exactly. On the first run of that baseline, one of them came out like this:

1;2;4;6
3.000000
00:02:60.000000

Two minutes and sixty seconds. The route is right; it’s exactly 180 seconds. The time adds up to something like 179.99999 in floating point, the code truncates it with (int) to get the minutes, gets 2, and then prints the leftover, which printf rounds back up to 60. It had been printing that since 2023. The fix rounds to milliseconds before splitting the time up. That baseline line is the only one the whole project was allowed to change.

One line per event

With the hooks in place, a new function, run_trace, prints one line for each thing that happens. This is the real output for the map on the project page, where road 2→4 drops to 5 km/h 30 seconds in:

pop 1 0.000
relax 1 2 60.000
relax 1 3 90.000
pop 2 60.000
relax 2 4 120.000
relax 2 5 210.000
...
plan 1 2 4 6 180.000
move 1 2 0.000 60.000
update 2 4 5.000 60.000
replan 2 60.000
pop 2 0.000
...
plan 2 5 6 180.000
move 2 5 60.000 210.000
move 5 6 210.000 240.000
done 240.000 4.000

Look at the times after replan 2 60.000. The next pop 2 says 0.000, and the new plan says the trip takes 180.000, but the car arrives at 240. Both are right. When the car replans, Dijkstra starts again from node 2 with a fresh clock, so everything it prints is relative to that moment. move, update and done use the real clock. My own spec got this wrong: it had the second plan at 240.000, and I only fixed it after the real C printed 180. The JavaScript keeps the clock of the last replan and adds it to every Dijkstra event after it.

The trace also shows things the code never mentions. Node 5 is relaxed twice, at 210 and then at 156, because our heap has no decrease-key. It just inserts the node again and leaves the stale copy in the queue. And pop 4 720.000 shows up after the destination is already closed, because the loop doesn’t stop early. Both behaviours were in the code all along. I only saw them once they were printed one per line.

Reading a file that isn’t a file

The original program reads its map with fscanf from a FILE *. A web page has no file to hand it, and I didn’t want a second parser just for the browser. fmemopen solved that: it opens a string as a FILE *, so run_trace takes the map as text and feeds it to the same three reader functions the CLI uses. The only cost was compiling with -std=gnu99.

For the browser, Emscripten compiles every file except main.c. Without a main, the module loads and waits. The page calls run_trace with the map as a string, collects whatever it prints through the module’s print callback, and gets back the whole run as text. It’s 49,687 bytes of WebAssembly, loaded once per page, and a run on these maps takes a few milliseconds. When you add a jam with the traffic editor, the page builds a new input and calls the C again.

Input from strangers

Before the traffic editor, the only input this program had ever read was files the three of us wrote. Now it reads whatever a reader clicks together. Three things broke right away:

read_updates read each line into char aux[50], so a long line wrote past the end of the buffer.
An update for a road that doesn’t exist walked the adjacency list off its end and crashed.
An unreachable destination crashed too, instead of saying so.

There was a fourth one, quieter. dijkstra sizes its arrays from the node count in the file’s first line, so a header claiming a billion nodes would have blown the stack. run_trace now refuses anything above a million.

None of these were bugs for the assignment: we never fed it bad files. Each one has a test now, and the CLI’s output for the original maps still matches the baseline byte for byte, apart from that one line.

Playing it back

On the JavaScript side, the trace goes through a reducer that turns each event into a full snapshot: which nodes are open or closed, the current plan, where the car is. All of them are computed up front, so play, pause, step and speed are just a position in an array. The canvas reads its colours from the site’s CSS variables on every frame, which is why the graph follows the light/dark toggle mid-animation without any extra code.

The C itself still prints three minutes as 00:03:0.000000, with the seconds not zero-padded. The README documents it now, and I’m leaving it.

Porting DOS assembly to the browser

2026-08-16T00:00:00Z

My tic-tac-toe game is written in 16-bit x86 real mode assembly. There is no compiler that turns that into WebAssembly. The instruction set, the segmented memory model and the DOS interrupts have no equivalent target.

So the plan is emulation: assemble the original source with NASM, link it into a DOS executable, and run that executable inside DOSBox compiled to WebAssembly. The WebAssembly here is the emulator, not my code, and I think that honesty matters more than the label.

The build already works: nasm -f obj assembles both source files without a single change, and Open Watcom’s linker produces a 3,244 byte DOS executable.

What the game actually does

It is 1,740 lines across two files. vca.asm holds the game: the command parser, the board, win detection. draw.asm holds the graphics primitives.

The entire game state is nine bytes:

tabuleiro    db    '         '

Nine ASCII spaces. A move overwrites one of them with X or C, and a new game is nine spaces again. There is no struct, no bitboard, no packing. The board is literally the string you would draw on paper.

Win detection is fully unrolled. Eight winning lines, two players, sixteen blocks of explicit cmp byte [tabuleiro + n], al, one after another, with no loop and no table of line indices. That single decision accounts for a good share of the 1,187 lines in vca.asm.

Everything on screen arrives by one of two routes, and the two have nothing in common. The position labels are BIOS text: int 10h with AH=02h to place the cursor and AH=09h to write a character in the ROM font, straight onto a graphics-mode screen. The board, the crosses and the circles are pixels, plotted one at a time by Bresenham routines the game implements itself.

One interrupt per pixel

draw.asm is 553 lines and contains exactly three int 10h calls. The third one is the whole graphics layer:

plot_xy:
        ; ... prologue: saves bp and every register it touches
        mov     ah,0ch
        mov     al,[cor]
        mov     bh,0
        mov     dx,479
        sub     dx,[bp+4]
        mov     cx,[bp+6]
        int     10h

AH=0Ch is the BIOS write-pixel service. Every line, every circle, every X on the board goes through it, one pixel per interrupt. Nothing is ever written directly to video memory at A000h, and none of the VGA planar tricks that made mode 12h fast are anywhere in the source.

The mov dx,479 / sub dx,[bp+4] is the other detail I like. VGA counts rows from the top; the game thinks bottom-left, like graph paper. Rather than convert at every call site, it flips the axis once, inside the only routine that touches a pixel.

The cost is easy to measure. The empty grid is two horizontal lines 313 pixels long and two vertical lines 297 pixels long: about 1,220 BIOS calls before a single move is played. A circle of radius 40 is another 250 or so. In the browser every one of those traps into the emulator instead of into real ROM.

It does not matter (a tic-tac-toe board is a few thousand pixels, and the thing draws instantly), but it does clarify what emulation is buying here. Not speed. Fidelity of a BIOS that has not existed in hardware for decades.

The shape of the bundle

js-dos takes a .jsdos file, which turns out to be a plain zip. Mine holds two files: VCA.EXE, and a 77-byte .jsdos/dosbox.conf telling DOSBox to boot the machine as vgaonly, mount the bundle as C: and run the executable. That is the entire packaging step.

The whole bundle is 2,236 bytes. The emulator that runs it is 1.4 MB of wdosbox.wasm plus another 315 KB of loader. The WebAssembly alone is 450 times the size of the 3,244-byte program it exists to run. That asymmetry is why the demo loads on a click and not on page load: someone who came to read about the project should not pay for a DOS box they never asked to boot.

Two things the browser half cost me

js-dos defaults pathPrefix to its own CDN. Leave it alone and the page quietly downloads 1.4 MB of WebAssembly from someone else’s server, which is exactly the thing this site is built not to do. The failure is silent: everything works, and the page just is not what I said it was. My existing check for third-party requests read src and href attributes out of the built HTML, so it was blind by construction: this request is born at runtime, inside JavaScript. The new check scans the published JavaScript for off-origin URLs instead.

The second one was louder. js-dos ships a stylesheet, and that stylesheet opens with a full Tailwind reset: h1..h6{font-size:inherit}, a{color:inherit; text-decoration:inherit}. It loads after mine, at the same specificity. Clicking “Play” flattened every heading and drained the colour out of every link on the page, all at once. The fix was to stop serving those 118 KB entirely and hand-write the handful of rules the emulator’s own DOM actually needs, scoped under .demo-screen.

The readme was wrong

The game’s readme says to type OLC to play a circle. The code compares against 'C', at vca.asm:80, and C22 is what worked when I first ran it under DOSBox. The messages never moved: the game still prints O Venceu and Vez do O. At some point the display kept O and the parser took C, and the readme followed the half that was easier to see.

So the demo documents C, and there is a test that fails if anyone helpfully “corrects” it back to O by reading the readme. It is a small thing, but it is the kind of thing that only surfaces when you actually run the program instead of describing it. Seven years later, that is most of what this port was for.