WebQuake: an HTML5 WebGL port of Quake that runs from a web server

Quake in a browser tab, with the original assets

WebQuake is an HTML5 WebGL port of the game Quake by id Software, and the important structural point is that it is a port, not a reimplementation with bundled content. The client does not ship the game. You supply the Quake resource files yourself, and the documentation says the demo version containing only the first episode is enough to get going. The engine and the runtime are the project's contribution, and the assets remain id Software's, which is why the installation steps are about copying folders around rather than downloading a package. The browser angle is what separates it from the original: no plugin, no native binary, and the game runs in a tab. There is an online demo hosted by SpiritQuaddicted, and the repository itself is small, with a Client/ directory, a Server/ directory, a README and a GNU.md file, which matches a project that is one engine port plus a multiplayer daemon.

The web server has to support HTTP 1.1 Range requests

The first installation step is the one that trips people up, because it constrains the server rather than the game. You need a web server with HTTP 1.1 Range support. The documentation states that the project was developed and tested on Abyss Web Server on Windows and says it is guaranteed to work there, which is a strong hint about what to use if you want a trouble-free setup. The reason range requests matter is the shape of the assets: the Quake resource files are large and are read from a running server rather than downloaded once, and a server that cannot serve byte ranges forces the whole file over the wire. After the server is chosen, the second step is to download the entire contents of the Client folder, that is index.htm and the WebQuake/ folder, and put them somewhere on the server. Everything after that is file copying.

Copying id1, and the case sensitivity trap on Linux

The resource copy is where most first-time installs go wrong, and one instruction is easy to skim past. Copy the id1 folder from a Quake installation next to the file you put on the server, and if you have the mission packs, repeat the same for the hipnotic and rogue folders. Then comes the sixth step, which reads like a footnote and is not: on a system with case-sensitive names, such as Linux, all game files except the code files must have lowercase names. Quake on DOS was not case sensitive, and resource names in the game data may not match the capitalisation you see in a file listing, so a copy that looks complete can still fail to load. Mission packs are selected from the command line rather than by a menu, with the -hipnotic argument for Scourge of Armagon and -rogue for Dissolution of Eternity. Custom mods work the same way: copy the mod folder into the folder containing index.htm and add the -game MOD_NAME_HERE argument, applying the same lowercase rule to the mod files.

Command line arguments and browser hotkeys

Launching WebQuake means navigating to the WebQuake directory on the server, and the address bar is also how you pass arguments. Put a question mark after the address and then the arguments in the same format you would use for Quake itself, so -hipnotic, -rogue and -game all work the way an original player expects. One browser detail catches people out: browser hotkeys such as F5, Ctrl+T and Ctrl+W are intercepted by the browser itself, so the documented workaround is to click the address bar first, and click the game when you are done with the address bar. Saving and loading is handled by the game, and the documentation notes that pressing Del in the load or save menus deletes saved games, with the caveat that this only works for saves created in WebQuake. If the sound stops playing, the console, reachable with the tilde key or through Options and Go to console in the main menu, accepts stopsound to fix it.

Multiplayer over WebSocket, with an https exception

Joining a game takes two routes. In the Multiplayer menu of the main menu you type the IP into the Join game at field and press Enter, or you type a connect command with the ws:// scheme straight into the console. The documentation also says you can play WebQuake games in a native Quake client such as WinQuake or GLQuake, choosing TCP/IP in the Join Game menu, so a local network can mix browser and native players. The catch is stated in one line and it is absolute: you cannot join multiplayer games if the client is installed on the https protocol. That is a hard boundary rather than a configuration problem, and it is the single fact that decides where this port can be deployed. A page served over https cannot open a ws:// connection, so a hosted copy of WebQuake over TLS is a single player experience unless the transport changes.

The dedicated server is a small Node.js program

Hosting is handled by a separate Server folder in the repository, and the setup is short. Install Node.js, download the Server folder, put the Quake resource files into it, open a Node.js command prompt, change into the Server folder, and run npm install websocket, which the documentation points at the Worlize WebSocket-Node repository for. To launch the server, run node WebQDS.js from the same folder, and the maximum number of players is set with the -maxplayers command line argument. The server also has a remote console, which is where the security trade-off appears. You set an rcon_password in the server console, and the documentation warns explicitly against putting that password on the command line, because everyone on the web can see the command line on the server's /rule_info page. The remote console can then be driven from the game console, from a browser page served by the server, or through a URL of the form /rcon/your_command_here, logging in as the user quake with the RCON password.

A JSON API for server state, and a browser matrix from 2013

The server answers plain HTTP requests with JSON, which makes it easy to build monitoring around. /server_info returns an object with the host name, the current level, the number of connected players, the maximum number of players and the protocol version, and it returns 503 when the server is off. /player_info returns an array of player objects with name, shirt and pants colour packed into one number, frags, connect time and IP address, /player_info with a player number returns one object, and both give 503 when the server is down and 404 when the player is not found. /rule_info returns every server console variable as a name and value pair, and /rule_info with a variable name returns one of them. The browser support section is the part to read with care, because the results are explicitly from 2013: Firefox and Chrome on Windows are rated very good, Firefox on Android is okay but the canvas is locked at 12 FPS, Chrome on Android is rated not good with broken sound and no mouse, Opera on Windows has a water rendering issue that the console command r_waterwarp 0 works around, and Internet Explorer is unsupported. Mouse support currently exists only on Chrome and Firefox, and stereo positional audio on Chrome and Safari. Music is handled separately, by converting the Quake CD tracks to .ogg files named quake01.ogg onwards, serving them with the audio/ogg MIME type and placing them in a media folder inside id1.

Editorial conclusion

WebQuake suits people who want to play or host Quake from a browser without installing a native client, particularly for LAN play or for a museum-style demo, since the client is plain static files and the server is a small Node.js program. It is the wrong choice for a modern multiplayer community, since the browser client only joins over ws:// and cannot connect at all when the page is served over https. Before deploying it, confirm the web server supports HTTP 1.1 Range requests, keep the case of the resource file names consistent, and read the remote console section, because the server exposes its command line on a public page.

Frequently asked questions

Official sources

1. Issues
2. README
3. Triang3l/WebQuake on GitHub