Forem: edA‑qa mort‑ora‑y

System Architecture for Edaqa's Room

edA‑qa mort‑ora‑y — Thu, 15 Apr 2021 18:34:58 +0000

I tried explaining to a friend how my games were setup, but it became confusing quickly. Drawing all the component boxes, I’m surprised to see how complex it has become. I think it’s a decent example of modern system architecture, and will go through the setup here. This is for a multiplayer game, so I’ll point out how this might differ from a more typical web application.

I could reasonably call this architecture the platform on which my game runs. A higher-level of code runs on top of, but is intimately tied, to this platform.

Client

I like to start at the user’s view on the system, as it keeps me grounded in the system's purpose. Mostly the user interacts via the website, but I also send email confirmation on purchase. The starting point to the game could be via the immediate web link, or the link in the email.

I was tempted to split the client into a game and website proper, as they are fairly distinct aspects of the system. But the discussion of the website’s logical structure is better left for another article.

Note the two lines from the browser to the HTTP server. One is normal HTTP traffic, and the other is for WebSocket. Though they go through the same machines, they are handled differently. I’ll provide more detail later, but the way I handle WebSocket is specific to a multiplayer game — a need for a fast response motivates the design.

In terms of fault tolerance, it’s the client which is most likely to fail. From browser incompatibility to crashes, and slow or lost connections, the client is an endless pool of problems. The servers are virtually faultless by comparison. As this is an interactive multiplayer game, it’s vital to handle common client problems correctly. The higher level code handles most of the faults, which this architecture supporting it.

Cloud Processing Services

The three red boxes contain the abstract aspects of the cloud service. These services are mainly configurations and I have no insight into their internal structure. They contain only transient data.

Content Delivery Network (CDN): The CDN serves all the static assets of the website and the game. Most of these resources use the web server as the origin, as it gives me the cleanest control over versions. The CDN provides faster loading to the client and reduces load on the host machines. I could do an entire article on the challenges of getting this working. (Service: AWS CloudFront)
HTTP Frontend: This takes care of the incoming connections, as well as SSL handling. It provides, when needed, a slow rollout to upgrading the hosts. It’s a security barrier between the public world and my private hosts. Thankfully, it routes both normal HTTP and Websocket traffic. (Service: AWS Elastic Load Balancer)
Email Sender: Sends purchase confirmation emails to the user. I mentioned the client layer is fault prone, and email is no exception. You absolutely want a third-party service handling the challenging requirements of modern email. (Service: AWS Simple Email Service)

Host

My host contains several microservices, which I’m grouping into a large block. With Python as the main server language, I was forced into the microservice architecture. Separate processes is the only way I can get stability and parallel processing of these services.

These are all launched as systemd services on an AWS Linux image.

Web Server: Handles all web requests, including static files, templates, game launchers, and APIs. These requests are stateless. (Service: Python Code with Eventlet and Flask)
Game Server: Implements the game message queues, which are shared message rooms per game — think of it like a chat server with channels. This is stateful per game. It handles client connections and transmits messages but does not understand the logical game state. For fault tolerance, it was vital that misbehaving clients don’t interfere with other games. (Python Code with Asyncio and Websockets)
Message Service: Migrates game messages from the live database to the long-term database store. This happens regularly to minimize the memory use of the live database, allowing more games to live on one host. (Service: Python Code)
Confirm Service: Sends emails when somebody purchases a game. I avoid doing any external processing in the web server itself, instead having it post a job that is handled by this service. This keeps the web server responsive and stable. (Service: Python Code)
Stats Service: This is a relatively fresh addition, needed for my affiliate program. I previously calculated game stats offline for analysis, but am working on features to present those at the end of the game. There is a bit of ping-pong with the web server to get this working. This is external, as it has slow DB queries and slow processing. It operates sequentially, as I do not want multiple stats running in parallel. (Service: Python Code)
Live Database: Contains game state for all games on this host. The game uses a sequenced message queue. For a synchronized visual response between players, it is vital this service is fast. Therefore I use a local Redis store to keep live messages, with the message service moving them offline. (Service: Redis)
Message Queue: Provides the message queue for these services to talk to each other. This is per-host because a few of the services need access to the Live Data for a game. The Confirm service does not need live data, and I could orchestrate the stats service to not need it either. However, having an additional shared message queue is unnecessary overhead. (Service: Redis)

The diagram creates siblings of the Live Database and Message Queue boxes, since the same process implements both. This is another point where the needs of the game dictate this local Redis server. Most web apps can probably use an off host queue and an external DB service. When you look at my alternate design later, you’ll see I’d be happy to have this part even faster.

I estimate a host can handle at least 100 concurrent games, around 400 users, and I dream about the day when I need many hosts. I can also add region specific hosts, providing faster turnaround for groups playing in other countries.

WebSocket

The diagram shows two different connections between the client and the HTTP Frontend, which continue to the backend.

The black HTTP connection is stateless, and it doesn’t matter which host it ends up at. Ultimately, when my dreams of high load come to fruition, I’d separate this, putting it on a different host pool, or potentially recreate it as lambda functions.

The orange WebSocket connection is stateful and must always arrive at the same machine. This is sticky per game; all players of the same game must reach the same machine. This must be done as a single host to minimize turnaround time. Shared, non-local queues, lambda functions, and DBs, all introduce too much of a response lag. This is particular to a multiplayer game.

Alternate Game Server Design

Again, I’m kind of forced into the above architecture because of Python. Should I ever need more performance, or wish to reduce hardware needs, I’d reimplement this, likely choosing C++, though any compiled static language with good threading and async IO would work.

A new single server would be a single application replacing these services:

game server: Depending on the language and framework, this socket handling code could look very different. Much of the speed improvement though would come simply from better data parsing and encoding.
message service: I’d gain more control over when this runs and have an easier time reloading messages for clients
stats service: I would make this a lot simpler since it wouldn’t need as much cross-process coordination to work.
live database: Simple in memory collections replace the Redis DB, providing faster turnaround, but complicating persistence and fault management.
message queue: The remaining job messages would migrate to a shared queue, like SQS.

This alternate architecture is simpler, at least to me, and I estimate it could easily handle 100x as many games on a single host. Or rather, it’d let me handle as many games as now, but with several much smaller hosts. That would improve fault tolerance.

Added coding time keeps this on the long-term backlog. Unless some here-to-unknown feature appears where I need this, it’ll be cheaper to keep the microservices model and spin up more hosts as required.

An intermediate solution is to code strictly the websocket channels in another language, since it’s the most inefficient part. Though I recently reprogrammed this part, still in Python, to be massively more efficient. New rewrites are on the long-term backlog.

Storage

The storage boxes contain all the long-term data for my game. There are no game assets here; I store them on the host where I upload each game. This provides the easiest way to manage game versions.

Media Store: Holds large static assets which aren’t part of the game proper, such as trailers and marketing materials. I synchronize this on-demand with a local work computer. (Service: AWS S3)
Log Store: Collects and stores the logs from the HTTP Frontend. I analyze these offline regularly. (Service: AWS S3)
Database: This is the heart of my business data, storing purchase information and persisting long-term game state. (Service: Mongo)

What’s Missing

I’ve left several components out of the diagram to focus on the core experience. I’ll describe them briefly here.

I don’t show monitoring, partially because it’s incomplete, but also because it’s merely a line from every box to a monitoring agent. The structure doesn’t change for monitoring, but it’s part of the live environment.

I’ve left DNS out of the diagram for simplicity. I use multiple endpoints for the client, the web server and the CDN, as well as for email, which adds up to many DNS entries. In AWS one has Route 53, but the individual services can thankfully configure, and maintain most of their entries automatically.

I have many offline scripts that access the database and the log store. This includes accounting scripts which calculate cross-currency payments and affiliate payouts — world sales with tax are a nightmare! I also do analysis of game records to help me design future games.

There’s an additional system used to manage the mailing list. As the sign-up form is part of the website, and people can follow links from the emails to the website, it is a legitimate part of the architecture.

Layers upon layers

I’m tempted to call this the hardware architecture, but with cloud services, everything is logical. It’s a definite layer in my system. Can I call it the “DevOps Layer”?

The website on top of this is fairly standard, but the game is not. I will come back and do some articles about how the game functions. I can also show how the system architecture and game architecture work together.

Other than a few game specific parts, the architecture is fairly standard for an internet application. I believe this is a good approach to what I needed.

Highly inefficient invisible animations (CSS/Firefox/Chrome/React)

edA‑qa mort‑ora‑y — Sat, 16 Jan 2021 16:06:46 +0000

The cursor in my text editor was lagging. It’s quite unusual given my 8 cores machine with 32GB of RAM. While tracking down that issue, I discovered that my escape game was consuming 20-30% of the CPU while idling. That’s bad! It turns out it was invisible elements being rotated via CSS.

It’s a bit of a pain. This means we need to remove all those elements which fade-away, otherwise they pile up and create load. Here I’ll show you my solution using React — the top-layers of my game are in React, that’s why I used it. I’m not suggesting you use React to solve this problem. But if you have animated HTML elements, get rid of them if they aren’t visible.

The Problem

While loading scenes, I display an indicator in the top-right corner of the screen.

This fades in when loading starts and fades out when loading is done. I wanted to avoid an abrupt transition. I handled this with CSS classes to hide and show the element. My React code looks like this:

    <SVGElement 
        url={url}
        className={RB.class_name("load-marker", className, is_loading && 'loading')}
    />

SVGElement is my component to load SVG files and display them inline. An img tag will perform the same way for this setup. The key is the is_loading && ‘loading’ part of the className attribute. This adds the loading class name to the element while it’s loading. When finished loading, I remove the class name.

This is the CSS (SCSS):

.load-marker {
    &:not(.loading) {
        animation-name: fade-out;
        animation-fill-mode: forwards;
        animation-duration: 0.5s;
        animation-timing-function: ease-in-out;
    }
    &.loading {
        animation-fill-mode: forwards;
        animation-duration: 0.5s;
        animation-timing-function: ease-in-out;
        animation-name: fade-in;
    }
    @keyframes fade-out {
        from {
            opacity: 1;
            visibility: visible;
        }
        to {
            opacity: 0;
            visibility: collapse;
        }
    }
    @keyframes fade-in {
        from {
            opacity: 0;
            visibility: collapse;
        }
        to {
            opacity: 1;
            visibility: visible;
        }
    }
}

I have an urge to digress into a rant about CSS's animation system! I've written animation and layout systems before, and argh, this is acid thrown in my eyes. Indeed, that system has a clear adding and removing animation support, making this whole setup trivial. But this is CSS, and, alas…

When an item loses the .loading class it will transition to a transparent state. The problem however came from some other CSS:

.loader {
    svg {
        animation: rotation 6s infinite linear;
        overflow: visible;
        position: absolute;
        top: 20px;
        right: 20px;
        width: 70px;
        height: 70px;
    }
    @keyframes rotation {
        from {
            transform: rotate(0deg);
        }
        to {
            transform: rotate(360deg);
        }
    }
}

That infinite bit is the problem. It’s irrelevant that we’ve faded the opacity to 0, the animation is still running! Firefox still does a style and layout update, each frame. Why it ends up consuming so much CPU, I have no idea. Chrome also consumed CPU, but only around 10%. Note, 10% is still ridiculous for a static screen.

I could also “solve” the problem by not spinning the item unless something is loading. This creates a rough transition where the icon abruptly stops rotating while fading away. Not good.

The Solution

I have two animated indicators, the loader and a disconnected icon, for when you lose the WebSocket connection to the server. I abstracted a common base component to handle them the same. This is how I use it, for the loader:

export function Loader({ is_loading }) {
    return <HideLoader
        url={theme.marker_loading}
        is_loading={is_loading}
        className="loader"
    />
}

This is the implementation:

function HideLoaderImpl({ is_loading, url, className }) {
    const [ timer_id, set_timer_id ] = React.useState(0)

    React.useEffect(() => {
        if( !is_loading && !timer_id ) {
            const css_duration = 1000
            const new_timer_id = setTimeout( () => set_timer_id(0), css_duration )
            set_timer_id(new_timer_id)
        }
    }, [is_loading]) // only trigger on an is_loading change

    const visible = is_loading || timer_id
    if(!visible) {
        return null
    }

    return (
        <SVGElement 
            url={url}
            className={RB.class_name("load-marker", className, is_loading && 'loading')}
        />
    )
}

const HideLoader = React.memo(HideLoaderImpl)

At first glance, it’s not obvious how this achieves a delayed removal of the element. The HTML generation is clear, when visible is false, then display nothing. When true, display the element as before, with the same logic for setting the loading class name.

If is_loading is true, then visible will be true. This is the simple case. But there is the other true condition when we have a timer_id.

The setTimeout callback does nothing but clear the timer_id when it’s done. At first I suspected I’d have to track another variable, setting at the start and end of the timeout. It turns out that all I need to know is whether there is a timeout at all. So long as I have a timer, I know that I shouldn’t remove the element.

The condition list to React.useEffect is important here. I provide only is_loading — I only wish for the effect to run if the value of is_loading has changed. Some style guides will insist that I include timer_id (and set_timer_id) as well in the list. That approach defines the second argument to useEffect as a dependency list, but this is incorrect. It’s actually a list of values, which if changed, will trigger the effect to run again. The React documents are clear about this. Yet also say it’s a dependency list, and recommend a lint plugin that would complain about my code. That recommendation makes sense for useCallback and useMemo, but not for useEffect.

Adding timer_id to the list would be wrong. When the timer finishes, it sets the timer_id to 0. That change would cause the effect to trigger again. This is a case where we do “depend” on the timer_id value, but we shouldn’t re-execute when it changes, as that would end up creating create a new timer.

In any case, this simple code now does what I want. It defers the DOM removal of the element until after the end of the animation. Well, it defers it one second, which is long enough to cover the 0.5s CSS animation. It’s complicated to keep these times in sync — more fist shaking at the CSS animation system!

If you’ve got an eye for defects, there is one there. The loader icon can be removed too early: when is_loading becomes true, then false, then within one second becomes true and false again. I don’t create a new timer if one already exists, so the deferral time will still be from the first timer. In practice, this will not likely happen, and the impact is minimal. The fix is to cancel an existing timeout and always create a new one.

My lagging cursor

I never got an obvious answer why my cursor was lagging. There were all sorts of applications, idle applications, consuming 5-10% CPU. It’s perhaps a real cost of high-level languages. More on that another day. I still hope that future apps will strive for less energy use.

For now, remove all those invisible animated HTML elements.

High-Throughput Game Message Server with Python websockets

edA‑qa mort‑ora‑y — Sat, 05 Dec 2020 22:14:02 +0000

An error came up during a competition with my game. One of the 80 players got stuck. Like really stuck: a breaking defect! The error should not have happened, could not have happened, yet it did. The only possibility was the Web Socket stack I use. Turns out that layer didn’t work as intended, and there was no way to fix it. Alas, I sought an alternate solution.

Here I describe what I came up with: a new, more focused stack, using Python websockets. Lots of coroutines, asyncio, and queues. I have the complete working example at the end of this article. This is likely the last state where it can standalone; I’ll be changing it to fit even tighter with my game code.

Logical Structure and the Problem

My game is a multiplayer puzzle game coordinated by messages. I segregate each instance of the game from the others. For messages, I do this with the classic “rooms” concept. It’s the name that Flask-SocketIO uses as well, and that’s what my first implementation used.

Mostly, messages in the game don’t need a defined total order. They can arrive in a different order to the different clients. There are a few situations where this isn’t true however, places where I need some messages to have a defined total order. There aren’t many of them, and that’s likely why I didn’t notice the defect earlier.

When I first started the project I asked whether the library, if used on a single client system, echoing in order, could maintain an order to the clients. The answer was yes, but the truth is no. Given the load is mostly network bound, it usually maintains an order. Only in a few stress times, or because of dumb luck, it sends messages out-of-order.

Fine, I can probably put a queue around it. Ugh, the throughput drops to an abysmal 70msgs/s. Without the queue it was already a slow 1200msg/s, but that was enough for my game. After a bit of back-and-forth, me and the library author disagree on what is acceptable throughput.

So I grabbed the websockets library instead, whipped together a proof of concept, and got 12,000msgs /s. Yeah, that’s more like I’d expect.

Actually, I’d expect even more. And long term, if I get enough traffic, I’ll rewrite this in C++. The throughput should be entirely network bound, but it’s still CPU bound on the server. I’ve done a lot of low-level networking before to know I can push it higher, but for my needs now, 12K/s is way more than enough. I’d likely scale the number of servers before worrying about optimizing one of them.

On to the code!

A Python websockets Messaging server

The “websockets” module is a minimal implementation of WebSockets. That sounded like what I wanted. I didn’t want to go to the low-level of handling the protocol. This left me writing all my high-level logic, in particular the client rooms.

The library is easy to use. I got a basic example working with little effort. Of course, then there are lots of details to cover. Here’s a quick list of things I needed to support, features first:

-Handle an incoming client where “handle” is mainly done by the library
-Allow a client to join a game room (each client can only join one room in my system, simplifying the code)
-Allow another client to join the same game room
-Allow other clients to join other rooms
-Allow a client to send a message
-Provide a total order to the message, with a message id
-Dispatch that message to all clients in the room

In my final code I’ll persist the messages to a Redis store, then eventually to a MongoDB. That is not part of my example code.

And there are several situations, or errors, that I’d have to deal with.

-A client disconnects cleanly or abruptly
-The client sends crap
-The client is slow
-Cleanup a room if there are no more clients in it

Structure

My server maintains a list of clients in a list of rooms:

@dataclass
class Client:
    socket: Any # What type?
    id: int
    disconnected: bool = False

@dataclass
class Room:
    key: str
    clients: Dict[int,Client] = field(default_factory=dict)
    new_clients: List[Client] = field(default_factory=list)
    msg_id: int = 0
    event_queue: asyncio.Queue = field(default_factory=asyncio.Queue)
    listening: bool = False
    future: Any = None # What Type?

I use type annotations for my Python, along with MyPy to check the types. Alas, for several library classes I’m unsure of types. Since many of them are created automatically, or are returned from other functions, it’s difficult to determine the type. I will eventually find out all the types.

In these data types, the socket is the only part directly connected to the “websockets” module. It tracks the incoming connection and used to send and receive data.

In brief, the listen_room function handles the incoming client connections. I push all messages onto the event_queue of the Room. The listen_room function listens to this queue and sends messages to all clients in the room.

One listener per room

I initially had a single listening queue that handled all the rooms. When I eventually write the lower-level server, like in C++, I’d keep this structure. When you get low-enough level, you can control a lot more details, removing the need for coroutines entirely.

But in Python there are a few reasons I’m using one listener per room:

-not overhead
-Redis
-bad clients

Overhead is all my Python code, and the library code, surrounding the writing to the clients. It’s not a lot, but it can add up with a lot of activity. I suspect the JSON parsing and formatting is the biggest part of it. But this is not a reason I have one listener per room. Since the Python code is running as a single real thread, it is irrelevant whether this code happens in one listener, or many listeners. It’s all unavoidable computational load.

The first real reason, Redis, is the well-behaved motivator. For each outgoing message I have to create a unique message id. In the sample code I track this in Python, in the Room class. On my final server, I’ll track this in a Redis integer key. Additionally, I’ll store all messages in a Redis list. A separate process will clear this regularly and persist the messages to a MongoDB. The calls to Redis take time, time that the server could instead process messages for other rooms. Thus I want to segregate the rooms. While one room waits on Redis, the others can continue processing.

The second reason, bad clients, is an unfortunate need. It’s possible that a client gets disconnected, or fails to process messages quickly enough. For the most part, this is handled by buffers. The calls to socket.send are effectively asynchronous, at least until the queue fills up. When that happens, send will wait until there is space in the queue. While waiting all the other rooms will stall, being unable to send any messages. By having one queue per room, I limit the damage of a client to that room only.

This won’t likely happen. First off, the websockets library has a timeout feature. Unresponsive clients will be disconnected long-before the outgoing socket buffers get filled up. My game simply doesn’t generate enough messages to ever fill the buffers. Extrapolating from my stress test, with an estimated average message size, there is room for 25K game messages in the standard buffers. And a typical run-through of my game, with a team, generates only 3 to 4 thousand messages.

In any case, it’s good protection to have.

`clients`, `new_clients` and memory

One advantage of having a single real thread is not needing to worry about actual data races. They simply don’t happen as they would in a multi-threaded application. Yay! No memory corruption is possible.

It doesn’t mean that race conditions, something different, don’t happen. The logical concerns of concurrency still exist, though to a lesser degree. Thanks cooperative threading! The most significant concern in my code is with the clients object. The queue listener iterates over the clients. If the list is modified during the iteration, Python will throw a concurrent modification exception. That is a strict no-no, as the iterator has no idea what it should do.

There are three cases where the list needs to be modified:

-when a client disconnects in listen_socket
-when a client disconnects in listen_room
-when a new client joins the room

At first I handled disconnect in the listen_socket function, but through testing noticed it can be a socket.send() call that detects the disconnect first. Thus the disconnect happens in multiple places. In both cases, I merely mark the client as disconnected in the Client structure. The listen_room skips disconnected clients while sending messages. It’ll track them and safely remove them from the room after the iteration loop.

When a new client joins the room, listen_socket adds it to the new_clients list. listen_room will then add new clients prior to each message loop. It does this just after retrieving a message to ensure that all new clients get the message. This means that the room messages can arrive at a client prior to the “joined” response from joining the room. In my game, getting this ordering, along with sending old messages, is important for clients getting a consistent game state. I’ll likely have to adjust this code a bit.

At no point does listen_socket know if it’s safe to work with clients, since it can’t tell if listen_room is inside or outside of the loop. A lock isn’t a bad idea, but it introduces an avoidable delay on the incoming listening side, and delays in the room listener. Why lock when I don’t have to?

In retrospect, it might be a disadvantage that much of the coroutine parallelism is implicit, especially if using something like eventlets. As a programmer, it’s less apparent where the logical thread switching happens. You just have to know that every await operation, every asyncio call, and every websocket call is a potential location for a thread switch. It’d be nice to say you should assume a switch is possible at any time, but then I couldn’t rely on it not switching in some places and would require a bunch of locks.

Use locks if you aren’t sure. Performance is irrelevant if your game breaks. grumble

Stats and throughput

I added a simple Stats class to track throughput on the server. It emits timings for all the incoming and outgoing messages per room. The 12K/s is what happens if I have multiple clients connected to unique rooms. My machine hits that 12K limit with the server process pegged at 100% CPU use.

Unfortunately, I must adjust my number down to 10K. Once I moved the rooms to individual listeners, I hit far more overhead. I’m not entirely sure why — I can’t imagine it’s the extra number of coroutines. Likely there are some tweaks in the async stuff to improve it, but it’s still fast enough that I’m not concerned.

As a curiosity, I measured a single client connected to the server. It’s getting slightly over 5Kmsgs/s. Since this is a client and server, I have two processes. They are both at 58% CPU use. Ideally they should be at 50% CPU use, since they send a message back and forth. That extra 8% is processing spent doing stuff other than handling the message. Perhaps if I wrote the system in C++ it’d get closer to 50%, but never reach there completely. The throughput however should go up.

When I say C++ would be faster, it’s because of my experience. I have better control of what happens and know how to use that control. It’s easy to get it wrong and up with a steaming pile that is worse than the clean Python version. Server code is hard!

The stats don’t directly measure response time. But knowing the ping pong nature of the tests, I can calculate roughly what that’d be. At fractional milliseconds per message, it’ll be noise compared to the true network overhead when deployed.

This statistics I calculate here aren’t great. If I were trying to write a truly high-performance server, I’d track averages, standard deviations, extremes, and record it all better. The numbers it’s showing are so over-powered for my game though that there’s no need for more.

Next steps

Now I need to get this integrated with my existing server. I think I lose the ability to use a single port and single Python instance. That’s not a big loss, it’s something I was intending on doing at some point, anyway. The game server shouldn’t be the same as the web server. This is both for performance and stability. Eventually, should I have enough load, I must run multiple game servers (multiple servers handling web socket connections). I have a plan to scale that direction, but it’ll be a long time before I get there.

Code

Below is the code for the server, the Python client, and a sample client for the browser. While the details may change slightly, the structure will stay close to this. Given the size of the code, it’s better not to spin this into a library. I’ll directly it adapt it for my game server.

This code is fairly stable and should work as a starting point for your own needs. Though of course, I can’t make any promises of that. I’ll likely discover things in my application that require fixes.

ws_server.py

from typing import *
from dataclasses import dataclass, field
import asyncio, websockets, json, time
from collections import defaultdict

#sys.path.append('../server')
#from escape.live_game_state import LiveGameState

def encode_msg(msg: Dict) -> str:
    return json.dumps(msg, ensure_ascii=False)

def decode_msg(text: str) -> Dict:
    return json.loads(text)


@dataclass
class Client:
    socket: Any # What type?
    id: int
    disconnected: bool = False

@dataclass
class Room:
    key: str
    clients: Dict[int,Client] = field(default_factory=dict)
    new_clients: List[Client] = field(default_factory=list)
    msg_id: int = 0
    event_queue: asyncio.Queue = field(default_factory=asyncio.Queue)
    listening: bool = False
    future: Any = None # What Type?

    def client_count(self) -> int:
        return len([c.id for c in self.clients.values() if not c.disconnected])

client_id_count = 0

rooms: Dict[str, Room] = {}


# Used to get a basic idea of throughput
class Stats:
    def __init__(self, name):
        self._name = name
        self._count = 0
        self._time = time.monotonic()

    def incr(self, amount = 1):
        self._count += amount
        if self._count > 5000:
            end_time = time.monotonic()
            print( f'{self._name} {self._count / (end_time-self._time)}/s' )
            self._count = 0
            self._time = end_time


async def listen_room(room):
    if room.listening:
        raise Exception(f'Already listening to {room.key}')

    room.listening = True
    print(f'Listen Room {room.key}')
    stats = Stats(f'Outgoing {room.key}')
    while True:
        qevent = await room.event_queue.get()
        if qevent == None:
            break

        # Add any new clients that have shown up, this handler must control this to avoid it
        # happening inside the loop below
        if len(room.new_clients) > 0:
            for client in room.new_clients:
                room.clients[client.id] = client
            room.new_clients = []

        # In my game I'll track IDs in Redis, to survie unexpected failures.
        # The messages will also be pushed there, to be picked up by another process for DB storage
        room.msg_id += 1
        qevent['msg_id'] = room.msg_id

        count = 0
        disconnected: List[int] = []
        for client in room.clients.values():
            if client.disconnected:
                disconnected.append(client.id)
                continue
            count += 1

            # There's likely some asyncio technique to do this in parallel
            try:
                await client.socket.send(encode_msg(qevent))
            except websockets.ConnectionClosed:
                print("Lost client in send")
                client.disconnected = True
                # Hoping incoming will detect disconnected as well

        stats.incr(count)

        # Remove clients that aren't there anymore. I don't really need this in my game, but it's
        # good to not let long-lived rooms build-up cruft.
        for d in disconnected:
            # Check again since they may have reconnected in other loop
            if room.clients[d]:
                del room.clients[d]

    print(f'Unlisten Room {room.key}')
    room.listening = False


async def listen_socket(websocket, path):
    global rooms, client_id_count
    print("connect", path)
    client_id_count += 1
    room: Optional[Room] = None
    client = Client(id=client_id_count, socket=websocket)

    stats = Stats('Incoming')
    try:
        async for message_raw in websocket:
            message = decode_msg(message_raw)
            if message['type'] == 'join':
                # Get/create room
                room_key = message['room']
                if not room_key in rooms:
                    room = Room(key=room_key)
                    rooms[room_key] = room

                    room.future = asyncio.ensure_future(listen_room(room))
                else:
                    room = rooms[room_key]

                # Add client to the room
                room.new_clients.append(client)

                # Tell the client which id they are.
                await websocket.send(encode_msg({
                    'type': 'joined',
                    'client_id': client.id
                }))

            elif room:
                # Identify message and pass it off to the room queue
                message['client_id'] = client.id
                await room.event_queue.put(message)
            else:
                # Behave as trival echo server if not in room (will be removed in my final version)
                await websocket.send(encode_msg(message))
            stats.incr()
    except websockets.ConnectionClosed:
        pass
    except Exception as e:
        # In case something else happens we want to ditch this client.  This won't come from
        # websockets, but likely the code above, like having a broken JSON message
        print(e)
        pass

    # Only mark disconnected for queue loop on clients isn't broken
    client.disconnected = True
    if room is not None:
        # Though if zero we can kill the listener and clean up fully
        if room.client_count() == 0:
            await room.event_queue.put(None)
            del rooms[room.key]
            await room.future
            print(f"Cleaned Room {room.key}")

    print("disconnect", rooms)


def main() -> None:
    start_server = websockets.serve(listen_socket, "localhost", 8765, ping_interval=5, ping_timeout=5)

    asyncio.get_event_loop().run_until_complete(start_server)

    asyncio.get_event_loop().run_forever()


main()

ws_client.py

A simple client that validates the correct ordering of messages. Provide a room on the command line.

There's an option to slow this client which forces the server to disconnect it when the buffers fill up.

You'll note my client test code is rougher than my server code, and lacking many type definitions. This code will not be used long-term, but the server code will be.

from typing import *
import asyncio, json, websockets, time, sys

if len(sys.argv) < 2:
    print(f"Sytnax {sys.argv[0]} room (delay)" )
    sys.exit(-1)

room = sys.argv[1]
# A non-zero slow creates a client that can't keep up. If there are other clients in the room
# it will end up breaking, causing the server to disconnect it.
slow = 0.0
if len(sys.argv) > 2:
    slow = float(sys.argv[2])

def encode_msg(msg: Dict) -> str:
    return json.dumps(msg, ensure_ascii=False)

def decode_msg(text: str) -> Dict:
    return json.loads(text)

# An even simpler stats tracker than the server 
trigger_count = 5000.0
if slow > 0:
    trigger_count /= (1+slow) * 100


async def reader(websocket):
    count = 0
    seq = 0
    last_time = time.monotonic()
    client_id = None
    last_msg_id = None

    async for message_raw in websocket:
        count += 1
        msg = decode_msg(message_raw)

        if msg['type'] == 'joined':
            client_id = msg['client_id']
        else:
            # Ensure the messages have a single total order
            msg_id = msg['msg_id']
            if last_msg_id is None:
                last_msg_id == msg_id
            else:
                if msg_id != (last_msg_id+1):
                    print(last_msg_id, msg_id)
                    raise Exception("bad msg sequence")

        if msg['type'] == 'ping' and client_id == msg['client_id']:
            # Ensure our own measures retain the order we sent them
            if msg['seq'] != seq:
                print(seq, message_raw)
                raise Exception("bad message seq")

        # Track rough throughput
        if count >= trigger_count:
            next_time = time.monotonic()
            print( f'{count /(next_time - last_time)}/s {room}' )
            last_time = time.monotonic()
            count = 0

        if client_id == msg['client_id']:
            seq += 1
            await websocket.send(encode_msg({'type': 'ping', 'seq': seq }))

        if slow > 0:
            await asyncio.sleep(slow)


async def hello():
    uri = "ws://localhost:8765"
    async with websockets.connect(uri) as websocket:
        print("Connect")
        await websocket.send( encode_msg({ 'type': 'join', 'room': room }) )
        consumer_task = asyncio.ensure_future(
            reader(websocket))
        done = await asyncio.wait(
            [consumer_task],
            return_when=asyncio.FIRST_COMPLETED,
        )


asyncio.get_event_loop().run_until_complete(hello())

ws_client.html

A simple web browser client, to prove that it's working where I need it.

<html>
<script>
function loaded() {

    console.log("Loaded")
    const socket = new WebSocket('ws://localhost:8765');

    socket.addEventListener('open', function (event) {
        socket.send(encode_msg({
            type: 'join',
            room: 'js-room',
        }));
        console.log("Opened")
    });

    socket.addEventListener('message', function (event) {
        console.log('Message from server ', event.data);
    });

    window.addEventListener('beforeunload', () => {
        console.log("UNLOAD")
        socket.close()
    })
    console.log("LOADED")

    let count = 0
    setInterval(() => {
        count = count+1
        socket.send(encode_msg({
            type: 'ping',
            seq: count,
        }))
    }, 500)
}

function encode_msg(msg) { 
    return JSON.stringify(msg)
}

function decode_msg(text) {
    return JSON.parse(text)
}

</script>
<body onload="loaded()">
    <p>Text</p>
</body>
</html>

Designing a Snacking Bear Puzzle

edA‑qa mort‑ora‑y — Mon, 23 Nov 2020 16:20:35 +0000

In this stream I design a snacking bear puzzle. Watch my, sometimes painful, process of assembling graphics, thinking about a puzzle, and putting it together.

First, the puzzle:

Check you answer

Now, the stream:

What I look for while play-testing

edA‑qa mort‑ora‑y — Mon, 23 Nov 2020 15:15:48 +0000

I’ve completed a lot of play-testing lately for my game Carnival. It’s a fascinating experience to watch people work through the puzzles. And it’s a humbling experience as people stumble and flounder on failings in my designs. Without a doubt, focused user testing has made my game significantly. Here I’d like to write about the principal things I’m watching for.

A friend of mine spurred this article, as she discovered I keep extensive notes during the play-test. She also tested the game and was curious to know if I wrote anything bad about her. I assured her it was all good stuff, while silently discarding the evidence behind my back.

Play-testing Process

Carnival is played online in the browser with teams that meet in an audio/video chat. While the faces can be helpful for testing, it’s mainly the audio I’m listening to. For the video, I have one participant share their screen. It’d be great if I could have all participants share their screens, but I’d probably need more monitors to make sense of it.

Hearing the people play is super useful, in addition to watching what they do on screen. Where they move their mouse can be telling, but hearing their “hmms” and “huhs”, exasperated laments, and cries of fowl, tell even more. All of this helps me understand their thought process in solving puzzles and easing the play for future players.

In the early rounds of play-testing, I instruct people about what to expect and how the game works. This allows me to test prior to the game being finished, avoiding some redundant work. I try to reduce the verbal preamble quickly as possible for subsequent teams, replacing it with the in-games systems. By the late stages of testing, I start with only a few hellos, then send the teams off on their own.

I don’t record these sessions. First off, I don’t care to deal with the privacy aspect of archiving such data. But second, I’d never watch them again. It’s almost always better to test with a new group of people than labour endlessly on a single session. More people equals better testing, especially with a puzzle oriented game.

Cryptic Notes

As mentioned, I take a lot of notes for these sessions, where lots means 2-3 pages of cryptic scrawling for the roughly 90 minute test sessions. A symbol showing the type of comment prefixes each line . At least in theory, in practice, I have some lines that have nothing before them. If something occurs to me during the test, I note it down, even if I’m unsure it’ll be helpful.

For clarity here, I’ll replace my symbols with emojis. That way we can debate their semantic importance, rather than dissect my post-modern scribbling approach to art.

🐟 Red Herring

This became the most important symbol in testing. Red herring’s a problem in puzzle games. These are things, an item, a graphic, some dialog, a pattern, virtually anything that misdirects the player. The player already has to resolve many important pieces of information in their head.

I’m talking about unintentional red herrings. These are colour patterns, or objects, that reasonable look like clues to a puzzle. They arise naturally out of the graphic design by accident. I have nothing but ire for designers who intentionally add red herrings in their game. It’s an undebatable poor design that frustrates players. There are enough unintended red herrings to deal with already.

For example, I have a puzzle in Carnival where you need to set a row of lights to the correct colours. I intend them to match another pattern on the screen, as hinted in some dialog. Lo-and-behold, some testers found another sequence of colours, in some flags, that seemed to match the lights as well. They then proceeded to match that pattern, which of course failed. This gets a big “🐟” mark in the notes.

🐟 sequence of flags matches light pattern

⭘ Obvious thing to change

Many small, sometimes large, obvious ideas crop up during the tests. These may be ways to improve the puzzles, graphics improvements, overall UX ideas, or basically anything. The ⭘ means I had a concrete thought and I should go back and improve it later — at which point I add a ✔ to it.

Each circle is a clear opportunity to improve the game. Rather than theorizing about things to improve, these all come from actual players. Fixing them would have a direct impact on some future player. This doesn’t mean they all get resolved, as priorities still play a role, and some of them are hard to fix.

One example I have is with a ticket in the game. The player acquires the ticket and must present it to get into the carnival. I thought it’d be obvious that you show the ticket to the man in the booth, but one player tried to use the ticket on the entry sign. It’s not ridiculous, since the sign, with a “No Entry” label hanging on top, is where you enter the park. What happens then is frustration. In their head the player has resolved the situation: they found a ticket and are using it to get inside. It not working is like throwing a wrench into their thought process.

The obvious resolution was to make the sign accept the ticket, and that’s the note I made:

⭘ tried show ticket to sign, accept ticket

Though, I ended up using a more humourous fix. The booth agent cracks a joke about an inanimate sign. This has the effect of affirming the player’s action made sense, but was slightly off. Additionally, it made it clear where the ticket should be used instead. Oh, I could talk at length about this leading…

🏁 Puzzle Solved

Whenever a player solves a puzzle, I note it with a little flag, and the time.

🏁 rabbit hand puppet, 23:03

This is the wall time, since it’s what I have most available. I record the start of the session as well, letting me calculate later the time offsets between puzzles.

My goal here is to establish a good pacing for the game. Droughts, long periods between solutions, demotivates the player, and increases the likelihood they dislike the game. Given my experience with the previous game, and numerous escape rooms I’ve played, the pacing mostly worked as is.

However, there were some clear problems on some puzzles — they took too long. In most cases, I didn’t need to know the time to see that people were frustrated. But sometimes the time helped decide the frustration was okay. Perhaps the player was being impatient, rather than having an actual problem.

Timing can also deceive. In one game the players took nearly 15 minutes for one puzzle, well beyond the typical 5 I consider a maximum — these aren’t like fundamentally fixed numbers, so don’t quote me on them. But after the puzzle they both said “wow, that was great” — or something to that effect, I can’t always read my writing. This makes evaluation tricky, but at least the timed notes give some help.

❓ Hint requested

Everybody gets stuck, but an experienced team should not need hints. It’s why I treat hint requests during play-testing seriously. The game has a built-in progressive hint system, so all I do is note where they requested the hint, and how many they needed.

❓❓❓ dart game

You might think requesting a lot of hints is bad, but for experienced teams, if they need one, they typically need many. This results from the hints being progressive; the players often already know the information in the first couple of hints, and only the later one reveals something new. Short of deciphering the players thoughts with electrodes plugged into their brain, there’s no real way to avoid this.

Well, there is a way to avoid some hints, and I do that. Some hints can be tied to game actions, in particular with the inventory. But the general purpose hints can’t be tied to in-game events. I can never really be certain the player already knows the hint.

Requesting hints is part of puzzle games. It’s totally fine if players ask for them, but it shouldn’t be the standard approach to solving a puzzle. And since people who play-test are mainly interested in this genre of game, it biases the results — I assume the average player will require more. It’s a good sign when some play tests have no ❓'s on them. Past that point, I can consider each tension point more carefully.

‟ What they said or did

To give context to my notes, and the players thought process, I take several notes about what they say, or what they do. The latter also uses quotes, because I couldn’t think quickly what other symbol made sense, and in practice the notes are mixed.

‟Is this random? click on light

These notes primarily serve as anchors to the other ones

I’ll also make notes of solutions they’ve tried that have failed. These can often give ideas of how they are thinking, or, sometimes, I end up accepting alternate solutions if they seem equally valid. For some of these I’ll end up using a CIRCLE-‟ combination in the notes.

⭘ ‟12345, hmm, doesn’t work

❗ Something is broken

I put this last since it’s not the point of this level of play-testing. I have already resolved most of the functional defects, and the game is fully playable before I begin play-testing. Several minor defects still appear, and if I’ve recently changed something, engine defects are possible (the frightening and thankfully rare ❗❗).

❗ B-girl font not converted path

The ❗ is for things that are 100% definitely technical defects. This could be a graphic that is missing, the wrong font used somewhere, or a typo in the text. I suppose I could use them for defects in the puzzles, though oddly, I’ve not have that situation come up yet. As this is a multiplayer game played over flaky networks, I’ve tried hard, from the start, to make the logical game state consistent. That appears to work. While defects are possible in the puzzles still, I’ve likely worked them out prior to starting play-testing.

I think that’s an important point: I’ve played the game entirely many times before I do any play-testing. I want play-testing to focus on the things I can’t find myself. Even the initial play-testers get a game that is working, albeit potentially without the hint system, and not all graphics in their final form, but functionally playable from beginning to end.

Scribbles

These symbols are a general guide to the notes I take. I still have other things written, sometimes in combination, or sometimes with no markings.

I have found though that trying to itemize my thoughts produces firm notes. Rather than write everything, and anything, I focus on specific action items:

-🐟 Something is misleading
-❗ something is broken
-⭘ Point for improvement
-❓ a puzzle may have a problem

Where 🏁 and ‟ are then used to anchor those points, giving context when I go back later.

While not a perfectly defined process, that’s about how I did play-testing of Carnival. Watching people play, think, and laugh is fascinating. I also love watching the streams of people playing my game, as it gives another insight. I take notes from those as well.

Edaqa's Room: Removing Red Herrings from Carnival

edA‑qa mort‑ora‑y — Sat, 24 Oct 2020 12:54:58 +0000

I go through the results of a recent play-test, removing some distractions and unintended misdirections.

This type of play-testing and corrections is a part of providing a smooth gameplay experience. I don't want people getting stuck on the wrong things. And without the play-testers, there's no way I can identify all those wrong things.

Edaqa's Room: Dev.to Special

Twitch Channel
YouTube Channel

All about the development of technology, graphics, and puzzles for my online escape and puzzle games. I'll show you how all the pieces work, how I design the games, and likely lots of poking fun at the Web.

Edaqa's Room: Sound and Music using WebAudio

edA‑qa mort‑ora‑y — Sun, 27 Sep 2020 13:50:45 +0000

Today I show you how I use Web Audio to add sound effects and music to my game.

Creating AudioContext
Loading sounds with XMLHttpRequest and decodeAudioData
Creating and playing buffers with createBufferSource
Using the Audio element for music
Fade in/out

Edaqa's Room: Dev.to Special

Twitch Channel
YouTube Channel

How to write a custom selector in React

edA‑qa mort‑ora‑y — Sun, 16 Aug 2020 18:32:46 +0000

What's an efficient way to react to global state updates in a React app? If using Redux, you'd use a selector. But I don't use Redux for my puzzle game, as I have my own state object. It works similar to redux — I have an immutable state which is completely replaced on modification. All changes in the logical game state are done there.

I used React's contexts to subscribe to state changes for the UI. This works, except parts of my UI are needlessly rerendered. The context update is sent upon any change, even if that part of the UI doesn't care about it. In practice this isn't too bad for my game, since I have few components listening, and pass properties down to memoized components. Still, I don't like inefficiency, and I know useSelector from other projects.

How could I get the selector logic in my own React code? I have a game state, and I know which parts I'm interested in, so it should be easy. I thought a long time about how it should be done, a lot more time that it took to finally implement. I'll cover what I did here, hopefully reducing the time you need to search for solutions.

What does React offer?

Somewhere in React is a subscription mechanism. That's how the components know to update when something changes. There are two options: context and state. They are both needed to build a selector.

Using a context is well documented. Nonetheless, here's a brief outline of how I used this prior to creating a selector. My actual code is TypeScript and has a layer of wrapping around this.

let GameContext = React.createContext([game_state, game_manager])
let game_manager = get_game_magically_from_global()

function MainComponent() {
    // I use React's state system to track the game state within this component.
    const [game_state, set_game_state] = React.useState(game_manager.get_current_state())

    // My game manager needs to tell me when the state changes.
    React.useEffect(() => {
        game_manager.watch_state(set_game_state)
    }, [set_game_state])

    // Provide the current state value to the context to pass down through the tree
    return (
        <GameContext.Provider value={[game_state, game_manager]}>
            <EdaqasRoomUI />
        </GameContext>
    )
}


function NiftyGameItem() {
    const [game_state, game_manager] = React.useContext(GameContext)

    const drop = React.useCallback(() =>
        game_manager.drop_item()
    }, [game_manager])

    return (
        <img onClick={drop} src={game_state.held_item.image} />
    )
}

I provide both the current game state and the game manager in the context. The state is for reading and the context for providing feedback. This is similar to Redux's dispatcher; my game manager also uses messages to communicate with the state.

The State

Notice useState in that example as well. For React, updating the context is no different than any other use of the state. The extra aspect of the context is providing that value to the descendents of the component. This is what the Provider does.

State can be used without a context as well. Here's a simple example as a reminder.

function ExpandInventory() {
    const [expanded, set_expanded] = React.useState(false)

    const toggle = React.useCallback(() => {
        set_expanded(!expanded)
    }, [expanded, set_expanded])

    return (
        <>
            <CompactView onClick={toggle} />
            {expanded && <GloriousFullView />}
        </>
    )
}

When the user clicks on the compact view, the browser calls the toggle function, which modifies the state. When the state is modified React will rerender the control.

JSX files create an illusion of close cooperative harmony between this code, the state, and the HTML DOM. The truth is a lot uglier. The HTML goes through React's diff engine, then is assembled into the browser's DOM tree. The callback function lives in the global heap, connected to DOM object, as well as being a closure over the stack frame in which it was created. The closure will be called in response to a user's click, far away from the stack in which the render code was run.

Understanding this structure is the key to making our own selectors. That set_expanded function can be called from anywhere and React will figure out how to update the component as a result.

Too many updates

Any component that needs the game state can call useContext(GameContext). The problem is that all state changes, whether they'd alter the component or not, cause the component to rerender. In my previous example, the NiftyGameItem only needs to update when held_item changes, yet currently it'll update anytime anything in the state changes. That's pointless and wasteful.

If I were using Redux, I'd use a selector to solve this issue.

const held_item = useSelector( game_state => game_state.held_item )

Only when game_state.held_item changes will the component rerender.

useSelector itself isn't magical. It is essentially a layer in between the state and the control. It will listen to every update to the game state, and run the selection function. But it will only update the component if the result of the selection function changes.

I wanted the same facility for my game state.

My own selector

useState is the primary hook into React's subscription system. At first, I looked for an explicit subscription API. What I wanted to do isn't directly covered in the state docs. But as I mentioned before, understanding how the callbacks, DOM, and state connect, assures me that my approach is correct.

What is the goal? This is what I want my NiftyGameItem to look like, ignoring the onClick part for a moment.

function NiftyGameItem() {
    const held_item = useGameState( gs => gs.held_item )

    return (
        <img src={game_state.held_item.image} />
    )
}

I only want to update when held_item changes. Let's jump right the almost final code.

type game_selector<T> = ( state : GT.game_state ) => T

export function useGameState<T>( gs : game_selector<T> ): T {
    const [_, game_manager] = React.useContext(GameContext)

    const [ state, set_state ] = React.useState<T>(():T => gs(game_manager.current_game_state()))

    React.useEffect(() => {
        const track = {
            current: state,
        }

        return game_manager.listen_game_state( (game_state: GT.game_state) => {
            const next: T = gs(game_state)
            if (track.current != next) {
                track.current = next
                set_state(next)
            }
        })
    }, [game_manager, set_state, gs])

    return gs(state)
}

    const [_, game_manager] = React.useContext(GameContext)

I get the game manger as I did before, but we'll have to come back and fix something here.

    const [ state, set_state ] = React.useState<T>(():T => gs(game_manager.current_game_state()))
    ...
    return state

I prep the state for the component. The game manager needs to provide the current state as it'll be needed when the component first renders, not only when the state updates. Here I don't track the entire game state, only the part that is of interest — the part extracted by the selector.

A selector function, gs here, takes the global state as input and returns the part to be watched. My useGameState code calls the gs selector function with the global state. The selector in my example is gs => gs.held_item, which retrieves only the held_item. In the game I have an on-screen indicator showing which item the player is currently holding.

I return the state at the end of the function. In the first call, this will be the initial state. In subsequent calls, for each new render of the control, it'll be the current state.

        return game_manager.listen_game_state( (game_state: GT.game_state) => {

The vital piece of code inside useEffect is the call to listen_game_state. I added this subscription function to the game_manager. The game manager already knows when the state updates, since it has to update the context. Now it updates the context as well as calling all the registered listeners. I'll show this code a bit further below.

        const track = {
            current: state,
        }

        return game_manager.listen_game_state( (game_state: GT.game_state) => {
            const next: T = gs(game_state)
            if (track.current != next) {
                track.current = next
                set_state(next)
            }
        })

Each time the state updates, the caller provided selector function is called to select a part of the state. This is compared to what value it had previously, and only if it has changed do we call the set_state function. If we were to call the set_state function every time, then it'd be no better than the caller listening for every state change.

Note the return. The listen_game_state function returns an unsubscribe function, which will be called whenever the effect is reevaluated, or the component unmounts. The game manager shouldn't hold on to components that are no longer around.

    React.useEffect(() => {
        ...
    }, [game_manager, set_state, gs])

The useEffect runs once when the control is mounted (or first rendered, more correctly). I have a dependency list of [game_manager, set_state, gs] for correctness. Should one of those change the effect needs to be reevaluated to grab the new values. In practice, these dependencies never change.

useState outside of a component?

It may seem unusual to call the useState function in something other than a react component. This type of chaining is allowed and expected. There's nothing special about calling useState directly in the component, or inside a function called by the component. React will understand which component it is in and associate it correctly.

I've not looked into precisely how this works. My assumption is that it's a global value that tracks the current component. The hook functions inspect that variable to figure out where they are and to register the appropriate listeners. I don't see another option, since useGameState is a plain TS/JS function — the JSX compiler has no chance to modify it. In threaded languages this stack would need to be thread local, but JS is single threaded (workers, etc. get their own global space, making them effectively thread local).

My selector is a combination of existing React functions: useState, useEffect, and useContext.

Hold on, there's a problem

I have an issue in the first line of the useGameState function:

    const [_, game_manager] = React.useContext(GameContext)

I reused the context from before, the one that provides the game state and the game manager. This is bad. Since it hooks into the game state context, this component will still be updated with every change of the state.

To fix this, I added a new context which contains only the game manager.

    const game_manager = React.useContext(GameManagerOnly)

This game manager never changes for the life of the game, thus no needless updates will be triggered by the call to useContext.

At this point I gain nothing by storing the game manager singleton in a context. I could simply refer to the global object from my useGameState code. However, to behave as a proper React app, I've left it in the context. This may also be important for your project, where the object isn't a singleton.

Save the batteries

Performance wasn't an issue for my game. Curiousity was part of the reason I wrote the selectors. The selectors do of course help; there were thousands of needless updates to components. Cutting back this processing time should help older machines, as well as saving battery power on tablets.

I'll continue to make optimizations where I see them. It may be inconsequential compared to the massive browser SVG rendering overhead, but there's nothing I can do about that. As my games get more complex the calculation will continue to increase. Keeping it performant can only help long term.

Plus, you know, curiousity. A solid reason to do something.

Check out how this all comes together in my game Edaqa's Room: Prototype. A collaborative online escape room full of puzzles, adventure, and probably no vampires.

Appendix: Game Manager subscription code

This is the listen_game_state code called by useEffect in useGameState. I've removed details about how I connect to my state object, for simplicity. If you'd like a closer examination of that part, let me know.

export type game_state_listener = (gs: GT.game_state) => void

export class GameManager implements StateChanged {

    gsl_id = 0
    game_state_listeners: Record<number,game_state_listener> = {}
    .
    .
    .
    listen_game_state( listener: game_state_listener ): ()=>void {
        this.gsl_id += 1
        const nid = this.gsl_id
        this.game_state_listeners[nid] = listener

        return () => {
            delete this.game_state_listeners[nid]
        }
    }

Subscription queues needn't be complex. On updates to the game state, the function below is called (part of the StateChanged interface).

    game_state_changed(game_state) {
        if( this.set_game_store ) {
            this.set_game_store(game_state)
        }

        for (const listener of Object.values(this.game_state_listeners)) {
            listener(game_state)
        }
    }

The first line goes back to the game_manager.watch_state(set_game_state) call at the start of this article. It's what updates the context storing the game state.

The loop is what tells all the useGameState listeners that something has changed.

I Wrote an Online Escape Game

edA‑qa mort‑ora‑y — Fri, 31 Jul 2020 18:35:28 +0000

I’m an escape room enthusiast, some may say addict, and for the past few months I’ve been missing it. A friend of mine, a true addict with over 500 rooms to his name, started organizing online competitions. After playing a few of the online games, I thought, “I want to build my own.”

So for that past couple of months I’ve been writing an online escape game — which you could say is a web puzzle game, but with the exciting flare of escape! It’s suitably called “Prototype”. I assumed that name would let me get away with some rough edges. This will be an evolving project, but the first installment is a success.

I’m proud of my game. I want to tell you how I made it.

Technology for the user

I had a few major goals for the game. These sit somewhere in the spectrum between user epics and use cases.

-Painless experience for the user: I wanted it all in the browser. These types of games are relatively short, and needing to download something would be a pain.
-A multi-player team experience: Real rooms admit teams of 2-6 or more players, and I wanted my game to allow the same. Additionally, a certain world crisis is an excellent motivator for remote team play.
-Painless registration: Beyond paying, I didn’t want any registration at all. This bugged me about many other games. Just let people play as quickly as possible.

Obviously clever puzzles and a fun experience were paramount, but it’s harder to quantify those directly. Those would be the product goals, and I felt the above points were critical to supporting those goals.

Given these requirements, I set out to write my own engine, as I saw nothing that would come close to what I want. I was picky with my game, not letting it get away with anything I’d complain about in other games. Naturally, a few priorities chipped a few notches in that plan.

Overall, I achieved those goals. Let me know where I should elaborate — priorities again, I don’t want to be writing blindly about everything!

A puzzling web stack

A design had been floating in my head for a while before I set down any code. There was some trial and error, but the architecture was stable from the start, with only a few deviations in method.

Here are some major pieces of the stack.

-React: Just React. No optional modules, no plugins, nothing. The core of React provided what I needed. Since I had a state machine, there was no need for something like Redux.
-Python and Flask: The server components, and game processing, are written in Python using Flask, with Flask-SocketIO, with Eventlet (always so unavoidable many layers here).
-Redis: A small, but essential part to coordinate the multi-player actions.
-SVG: I’m listing this as it’s a key part of the engine. Everything is based on SVG working well in the browsers. It was a major trouble point, yet surprisingly rewarding.

There are also the typical web server bits, using Jinja templates, talking to Mongo, Paypal… Zzz. Yeah, I’ll mention these bits more, but I suspect there’s nothing novel here.

Until late in the project, this was a mass of wiggling bits! I had many stressful days trying to juggle tech in my head. Getting something working was my primary goal, and I did that in stages. Now, as I write more games, I’ll keep refining the stack, but there won’t likely be any major architectural changes.

Languages are what I do

As a good friend of mine said, “No Edaqa project would be complete unless there’s a new language.” I’m too blinded by the beauty of languages to even catch a hint of criticism there.

The most important question of the technology is: did I want to write a game engine? The answer is a resounding “no!” I wrote the engine because I wanted to achieve my primary goals, saw nothing else that fit, and knew an engine was within reach. I wanted to design games. And I wanted to not be overly burdened while designing.

Thus there’s a domain-specific language for the games. It’s a high-level declarative language. I fully expect that long-term I’ll write other engines for it. My goal was to keep the game logic clean, without being bound to the engine. I want to write games and ensure that long-term I can maintain those games.

I’ll be happy to show you how the language works, what the preprocessor does, and how the game handles the code.

As they say, “Ask me anything”

I hit a lot of knowledge pockets and defects on this project. Not everything I did is obvious — and I hesitate to say some illogical bits remain. But I’m happy to talk about all of it.

Let me know what interests you the most, and I’ll answer what I can, providing more writeups where necessary. And if you like puzzles, or escape rooms, I invite you to play the game.

I encourage you to try the game, Prototype: A Game Master is Needed. It’s an escape game I wrote, and have lots to say about.

How I Evaluate You in a Code Interview

edA‑qa mort‑ora‑y — Wed, 30 Oct 2019 10:46:36 +0000

Many of my interview candidates do poorly as they don’t understand how I evaluate them. While other interviewers’ criteria vary, there are common themes. Knowing the basics helps you judge yourself and improve your technique.

At interviewing.io, I evaluate people on three categories. I think this fairly represents how various companies will rate you. Even if not explicitly considered, they’ll play a role in your overall evaluation.

problem solving
technical skills
communication

I’m asked to give a rating to each one, but they are intimately linked together. A candidate who lacks one ability will also appear to lack the others. Let’s take a look at each point here, trying to isolate its specifics.

Problem Solving

Problem solving is the part abstract from writing code. I want to understand your process, and not just the result. This requires that you know what the problem is, and what I’ll accept as a valid solution. Problem solving is a lot about defining constraints and finding ambiguities, or uncertainties, and resolving them.

The challenge varies depending on the question. My card game question requires you to write a small game simulation. I want to see how you approach this problem. I want you to ask questions. What exactly is a “card”, and how will you represent it? What does “deal” concretely mean?

Problem solving is about taking high-level requirements and translating them into concrete steps. If you’re working on a project, this would be the phase where you write user stories and user journeys. You don’t have to be this formal in an interview, but I want to see that you’ve understood the requirements. Tell me what you’re thinking and write the key points.

Show the inputs and outputs to the problem you’re solving. State whether you’re transforming data, or implementing a process. Describe how to break down the large problem into smaller ones. For an algorithm, mention related algorithms, and tell me how you’d adapt them to this new situation.

Identify what parts you recognize and how it’s analogous to something you’ve done before. If there’s a whiteboard, sketch out flow, data sets, and anything else in your head. Especially if you’re stuck, I want to know how you’re solving the problem. Never fall into a blank silent stare. I’m there to help you, but I can’t do that if I can’t follow your process.

And definitely don’t treat problem solving as a phase. I don’t expect you to come up with the perfect solution at the start of an interview. I want to see you take an idea and run with it. It’ll likely have problems and require corrections. I’ll even change the requirements on you, or criticize your approach. I want you to accept change and adapt.

💭 Your ability to solve problems depends on your technical skills. While problem solving is not a tangible skill, your designs are based on the real-world limitations of computers. It’s not possible to completely separate problem solving and technical ability.

Technical Skills

There are two major aspects of technical skills that I consider. The first is your experience in coding idioms and wisdom. Do you know what is possible and how to go about coding it? The second is specific language ability. Once you’ve said what you want to do, how well can you implement that in the language you’re using.

The first point is about your general coding knowledge. Are you aware of data structures, program flow, and all the things programming languages are capable of doing? This knowledge influences your problem solving ability, as this is your toolbox. Whether your design will work depends on whether the tools are available.

I evaluate the candidate here on how much they hesitate, or how quickly they work. I’m not judging the speed itself, but as an indicator of one’s proficiency with the tools. I’m also listening to how you speak, whether your voice carries confidence or is it an inquisitive tone seeking affirmation.

The second aspect, knowing the syntax and semantics of a particular language, is vitally linked to the first. How you express yourself in code is my primary window into understanding your general coding knowledge. If you’re struggling to write a loop, I have to decide whether it’s because you don’t know the language, or you’re uncertain of how a loop applies to the problem.

I’m looking at how smoothly you translate your ideas into code. For example, from my card game question, there is a phase of dealing the cards. You must split the deck into two stacks, one for each player. Whether you’ve chosen a loop, or a high-level splitting function, you should be able to write the code. Writing the wrong code, forgetting how a loop works, using the wrong splitting syntax, all reflect negatively on the candidate.

I don’t punish people for making mistakes. They happen. However, a pattern of similar mistakes, or outright repetition of previous errors, shows a lack of knowledge. If I spot a mistake I may ignore it, or I may ask you about the code. Being able to recognize mistakes reflects positively on your abilities.

Languages have a lot of features and I’m looking for how well you use them. Are you using enumerations and constants? Can you create a structure to encapsulate values? Are you correctly passing variables by value or reference? Do you use the standard error mechanisms?

I don’t expect you to know everything, but I expect you to know all the basics. For individuals claiming to be experienced in the language I’ll be looking for common idioms. For example, in Python I look at the use of list comprehensions and dictionaries. In C++ I’ll look for smart pointers and possibly lambdas. If the code is absent all the common language idioms, then it looks like the candidate is inexperienced in that language.

💭 When I conduct general interviews I don’t put a strong emphasis on language knowledge. Your code is one way that helps me evaluate you. However, if you’re interviewing for a specific position, that requires specific language knowledge, your language skills will be weighted more heavily.

Communication

Voicing your thoughts correctly is the best way to ensure I properly evaluate you. Candidates that cannot do this perform worse than others. Not only does speaking well improve my evaluation of your communication skills, it also ensures the interview goes smoother and you finish the code on time.

Talking is your buffer to mistakes in your code. If you just write code, then my only view on your abilities is through that code. If you tell me why you are writing the code, then I can understand your approach even if the code turns out to be wrong.

Which also means it’s pointless to read the code aloud. I can see the code and read it myself. Your words should express thoughts that aren’t explicit in the code. Many candidates recognize the need to talk, but I feel are unaware of what they should talk about. Thus they end up reading the code. Sharing your thoughts is something you can learn, but it takes practice.

Pay attention to programming vocabulary. You should know how to talk about software in industry terms. This reveals a lot about your experience and your attention to detail. I want to hear about concrete things, like instance variables, constant values, and calling functions with arguments. I want to hear you talk about popping items off a stack and enumerating the elements of a map. I don’t want to hear about “doing something with this thing here”.

I also don’t want to hear buzzwords. Don’t use terms you don’t know and don’t claim to know words that you don’t. Dishonesty is a major red flag in an interview. Don’t think you can get away with it. I’m good at spotting bullshitters, as are most people working in HR and many programmers who have done a lot of hiring.

Don’t worry about not knowing everything. I tailor my expectations based on your level of experience. Junior programmers have not been exposed to many concepts. Be open, honest, and inquisitive. However, I expect a lot from somebody with ten or more years of experience.

Interviews are interactive and communication ensures we’re both on the same track. A failure to communicate generally results in a misrepresentation of your problem solving abilities, and general programming knowledge. And the more I know what you are thinking the more I can help you towards solving the problem.

Conclusion

Generally it’s a lack of communication skills or problem solving that sinks a candidate. I can’t imagine a company that wants to hire somebody with either skill lacking. Okay, sure there are some cases where specific, and uncommon, technical knowledge is required. But even then, you’ll be competing with other candidates.

There are also individuals who can write basic code, but not apply their knowledge to new situations. They appear to have learned one particular approach without understanding any of the concepts behind it. I can’t always say how correct my impression is, as I go on what I see in the interview. This makes it imperative to show all these abilities.

You may be wondering how to demonstrate these skills. Obviously, to improve any one of them requires practice and study. But to show them all in an interview requires balance. Don’t keep your head stuck in the code. Be vocal about what your are thinking, this is the key way to reveal your knowledge and show how you’re solving problems. Don’t be afraid to show limitations in your knowledge, instead be open and show how you’re working around it. Talk to the interviewer. Sketch things on the whiteboard.

Be aware you are being evaluated, and on three primary things: problem solving, technical skills, and communication.

Merge Sort Quick Reference

edA‑qa mort‑ora‑y — Thu, 17 Oct 2019 07:35:59 +0000

Merge sort is a useful algorithm for sorting a list of items. It's an efficient and predictable algorithm. Inevitably it'll come up during your interviews, either you'll be asked directly, or you'll find it useful to solve a code challenge. This is a quick reference for merge sort.

Algorithm Design

Merge sort is a recursive algorithm that takes an unsorted list and produces a sorted version of it.

It is a stable sorting algorithm.

The divide-and-conquer algorithm splits the input in half, sorts both sides, and then combines the result.

Merge-Sort( input )
    if length( input ) < 1
        return input

    left-half, right-half = divide-in-half( input )
    left = Merge-Sort( left-half )
    right = Merge-Sort( right-half )

    out = []
    while not empty left or not empty right
        if front( left ) < front( right )
            out.append( pop-front(left) )
        else
            out.append( pop-front(right) )

Refer to sample code in Python.

Algorithm Complexity

The algorithm has a stack depth of log N. This is how deeply the recursive calls to Merge-Sort are nested. At each of these levels, it has half the input size, but the call is made twice. So effectively at each level, across all calls, the whole input is operated on. This is useful for the complexity.

The merge sort algorithm's complexity is not dependent on the input. The worst-case complexity is the same as the best-case complexity. It always performs the same number of comparisons and makes the same number of copies.

Time: Comparisons

The number of comparisons it the number of times two items are compared with each other. This is typically done using only the less than < comparison.

At each of the log n recursive levels the recombining requires n comparisons. This results in θ(n · log n) comparisons.

Time: Copies

The number of copies is the number of times an item is copied to a new location, either from the input or within the output.

At each of the log n recursive levels all of n items are copied into new output arrays during recombining. This results in θ(n · log n) copies.

The initial splitting may also do the same amount of copying. This does not change the upper bound, though in practical terms doubles the copying time. This is language dependent, it's possible to use a view on the input to avoid copying during the division stage.

Space

Each level of the recursion requires a copy of the input, as each level needs to combine the elements into new lists. This requires θ(n · log n) space.

Notes

Merge sort does not require random access to the elements, making it suitable for multiple container types, such as linked lists and arrays.

It allows for external sorting, meaning not all the data needs to be in memory at the same time.

View my video class that covers the design, complexity, and code of the algorithm.

Insertion Sort Quick Reference

edA‑qa mort‑ora‑y — Tue, 01 Oct 2019 15:03:47 +0000

Insertion sort is a commonly taught algorithm for sorting a list of items. Though not commonly used, as it's not efficient, it may come up during interviews. It also uses concepts that might be beneficial when writing other algorithms. This is a quick reference for insertion sort.

Algorithm Design

Insertion sort takes an unsorted list and produces a sorted version of it.

It is a stable sorting algorithm.

Insertion-Sort( input )
    output = empty list
    for each item in the input
        find location item in the output using upper bound (binary search)
        insert item at location in the output

Refer to sample code in Python.

Algorithm Complexity

Time: Comparisons

The number of comparisons it the number of times two items are compared with each other. This is typically done using only the less than < comparison.

For each item in the list n, the algorithm searches for the correct location using binary search O(log n). This puts an upper bound on the number of comparisons at O(n · log n).

Time: Copies

The number of copies is the number of times an item is copied to a new location, either from the input or within the output.

All items must be copied from the input to output, making a minimum of Ω(n) operations. If the input is in sorted order, this will be the number of copy operations.

In the worst-case scenario the list is sorted in reverse order. In this scenario each insertion into the output will need to move all existing items in the list. For each n items, there could be up to n copy operations. This is O(n²) copy operations.

Space

The algorithm needs to allocate space in the output for each item in the output. It needs no additional space. This is a space complexity of θ(n).

Notes

Due to its costly time complexity for copy operations, insertion sort is not typically used to sort a list. It is however an efficient way to insert a limited number of items into an already sorted list.

Inserting one item with insertion sort is O(log n), whereas adding an item to a list and resorting is O(n · log n).

View my video class that covers the design, complexity, and code of the algorithm.

Forem: edA‑qa mort‑ora‑y

System Architecture for Edaqa's Room

Client

Cloud Processing Services

Host

WebSocket

Alternate Game Server Design

Storage

What’s Missing

Layers upon layers

Highly inefficient invisible animations (CSS/Firefox/Chrome/React)

The Problem

The Solution

My lagging cursor

High-Throughput Game Message Server with Python websockets

Logical Structure and the Problem

A Python websockets Messaging server

Structure

One listener per room

clients, new_clients and memory

Stats and throughput

Next steps

Code

ws_server.py

ws_client.py

ws_client.html

Designing a Snacking Bear Puzzle

What I look for while play-testing

Play-testing Process

Cryptic Notes

🐟 Red Herring

⭘ Obvious thing to change

🏁 Puzzle Solved

❓ Hint requested

‟ What they said or did

❗ Something is broken

Scribbles

Edaqa's Room: Removing Red Herrings from Carnival

Edaqa's Room: Sound and Music using WebAudio

How to write a custom selector in React

What does React offer?

The State

Too many updates

My own selector

useState outside of a component?

Hold on, there's a problem

Save the batteries

Appendix: Game Manager subscription code

I Wrote an Online Escape Game

Technology for the user

A puzzling web stack

Languages are what I do

As they say, “Ask me anything”

How I Evaluate You in a Code Interview

Problem Solving

Technical Skills

Communication

Conclusion

Merge Sort Quick Reference

Algorithm Design

Algorithm Complexity

Time: Comparisons

Time: Copies

Space

Notes

Insertion Sort Quick Reference

Algorithm Design

Algorithm Complexity

Time: Comparisons

Time: Copies

Space

Notes

`clients`, `new_clients` and memory