23. WebSockets

In the previous chapter, we turned our text adventure into an online multi-player experience. To play the game, you needed a Telnet client. A Telnet client can still be found on most computers, but most computer users have never used it, and are not even aware it is there. But that is probably best for the safety of all. Securing a Telnet connection takes effort and skill; users are likely to give up, or worse, mess up.

Today, web browsers are the ubiquitous internet clients. Browsing the world wide web, we take for granted the security measures offered by modern web browsers. Wherever you go, encrypted connections and digital certificates help protect your digital identity.

So let’s see if we can use a web browser instead of a Telnet client. To make a web browser talk to our game server, they both need to use WebSockets. We need to do two things:

Based on that knowledge, I made the following HTML file. When opened in a web browser, it will show a very basic web page. There is an input field for the player to enter commands. The rest of the page is used to print the responses coming back from the game server.

www/index.html
<!DOCTYPE html> <meta charset="utf-8"> <title>Little Cave Adventure</title> <style> div { min-height: 1em; } div.in { border: thin solid silver; padding: 3px; } .in { margin: 1em 0; width: 100%; box-sizing: border-box; } #output:empty:before { content: 'Waiting for connection...'; } </style> <h2>Little Cave Adventure</h2> <div id="output"></div> <form name="lilcave" action="#"><input name="in" class="in" autofocus></form> <script> let prompt = false; const url = window.location.href.replace('http', 'ws'); const ws = new WebSocket(url); ws.onopen = function() { console.info('Socket opened', event); }; ws.onclose = function() { console.info('Socket closed', event); }; ws.onerror = function() { console.error('Socket error', event); }; ws.onmessage = function() { event.data.text().then(print); }; lilcave.onsubmit = function() { const input = this.elements.in.value; this.reset(); event.preventDefault(); ws.send(new TextEncoder().encode(input + '\r')); } function print(text) { for (let line of text.replace(/.\x01/, '').trimEnd().split('\n')) { if (line == '-->') { prompt = true; } else { const div = document.createElement('div'); const re = /\r\s\r/; if (re.test(line)) { line = line.replace(re, ''); } else if (prompt) { div.className = 'in'; } div.appendChild(document.createTextNode(line)); document.getElementById('output').appendChild(div); window.scrollTo({top: document.body.scrollHeight, behavior: 'smooth'}); prompt = false; } } } </script>

Explanation:

Line 1-2: minimal boilerplate intro for an HTML5 file.
Line 5: CSS rule to prevent blank lines in the game’s output from collapsing.
Line 6-7: CSS styling for the input boxes.
Line 8: initial text that will automatically disappear once the first piece of output text has been received from the game server.
Line 11: output section; this is where all the game’s output text is displayed.
Line 12: input section; this is where the user can enter commands.
Line 13-44: all JavaScript code is in this block.
Line 15: the web socket has the same URL as the web page, only the protocol is different; so all we have to do is replace http with ws (or https with wss).
Line 16: connecting to the server. For simplicity, we connect only when the page is opened; if players lose the connection, then they will have to refresh the page.
Line 20: every time the web socket receives text from the server, we automatically call function ‘print’ (line 29).
Line 22-27: this function is automatically called every time the player enters a command.
Line 23: retrieve the command from the input field.
Line 24: clear the input field, so that it is ready for the next command to be typed in.
Line 25: suppress the default behavior of the web browser to reload the entire page.
Line 26: send the command through the web socket to the server.
Line 30: text is sanitized (Telnet commands are removed), then split up into lines.
Line 31-33: with Telnet, we wanted the server to send a prompt to the client. The web page does not need this; it discards the prompt, but does consider it as a hint that the next line of text could be an echo of the command entered by the user.
Line 36-39: during the game, notifications about the activities of other players may be pushed to this client. With Telnet, such a message is preceded by whitespace characters to erase the prompt. The web page does not need this; we remove the clutter.
Line 45: let the web browser automatically scroll to the bottom of the (ever growing) page; that is where the latest output is.

It is doable, but still, it feels like a lot of work, and what for? Surely, I cannot be first person on earth that wants to make a translation between WebSocket traffic and standard Berkeley socket traffic. I went looking for something off-the-shelf.

One possibility is a C library. I tried Mongoose and it worked very well. Still, I did not like the many changes I had to make to my existing TCP server. In this article series, each chapter should be a small step forward. So I went looking for something less intrusive.

I settled for websockify. It is a straightforward command line tool. On a Linux server, there is a good chance you can install (and update) it straight from a repository. For example, here is how to install it on Ubuntu:

There are two possible ways to use websockify. The first one is to let websockify and lilcave run side by side.

This has the advantage that the same game is playable both from Telnet clients (port 18811) and from web clients (port 18812). If you do not care about Telnet support, then it is also possible to let websockify act as a wrapper around lilcave:

Open your web browser and navigate to http://localhost:18811/. Enter some commands to see if it works.

How about self-hosting the game? Traditionally, you would configure port forwarding on your internet router. This has the disadvantage that every player needs to know your IP address. It is the digital equivalent of inviting the whole world to your home address. In today’s world, it probably better to hide behind a proxy server. A very nice option is a Cloudflare tunnel.

Do be careful, this game is written in C, and C is notorious for its lack of memory safety. A small bug in the program may be enough to allow a smart player to hack your entire computer via a carefully crafted command.

Contents

How to program a text adventure in C

23. WebSockets