Basketball GM 4.0 technical details - caching, Shared Workers, IndexedDB/Promise interactions, Safari being a tease, McDonald's, and more

April 2, 2017-

Google made me do it.

Basketball GM has always allowed you to open up the same league in multiple tabs, so you can easily view multiple different screens. This was originally implemented by running the entire game in each tab. Game data was always saved to disk via IndexedDB. And when an action resulted in a change to the data (such as playing a game, signing a contract, trading a player, etc), then a signal was sent to all other tabs telling them to update their data. This was kind of a crude approach, but it worked.

It worked, until Chrome started throttling JavaScript in background tabs. Their logic was, if you're not even looking at the page, do you really want it burning through your battery? It made perfect sense. Except for Basketball GM, it meant that game simulation would only run if you were looking at the tab you started it in. So if you clicked "Play until playoffs" and then switched tabs, it'd never reach the playoffs. Fuck!

When life hands you lemons, make lemonade. Since Google decided to totally invalidate the tradeoffs I had considered when designing Basketball GM, I decided to re-evaluate. I came up with two ideas:

  1. If the current method of multi-tab play doesn't work, then I don't need to write everything to disk all the time. The only reason I was doing that was for cross-tab communication. Instead, I can keep a cache in memory, and then it should all be faster!

  2. Then, to restore multi-tab play, I can try to use some cross-tab communication technologies that didn't exist when I first made Basketball GM, specifically Shared Workers and Service Workers.

These would both be major changes to the core of the game code. I had considered doing both previously, but never made a serious attempt because it was so much work. But now, with Google fucking up multi-tab play, I really needed to do something. So I began "Project Iverson" (get it, speed?) and set off with great optimism working on the first task, replacing most database calls with a cache.

The basic idea of my cache is that all data needed for "normal" gameplay should be stored in memory. Database access should only be needed for viewing historical data. For example, all non-retired players are stored in memory, but retired players are not. So game simulation can happen without database access, and most pages can be displayed without database access. Only viewing pages that display retired players requires reading data from disk.

It sounds simple, but it's easier said than done. Some of the challenges included:

  1. If I read some data from the cache, that data is mutable, meaning that any changes I make to it will be immediately reflected in the cache. Good for performance, but bad if I have some code that is accidentally altering my data, which is possible because data read from IndexedDB can be safely mutated without affecting the database, so the entire game was not written with this mutability constraint.

  2. Previously I relied a lot on indexes to retrieve data. Like "get all players on team X" or "get me team stats from 2052", basically this is a built-in database feature to efficiently retrieve a subset of data. I needed to reimplement this in my cache. Even trickier, I needed to keep the indexes up to date even when data changes, with good performance. For example, if a player is traded from team X to team Y, then I need to make sure that the "get all players on team X" index does not return stale data.

  3. An in-memory cache also needs to eventually be persisted somehow. With IndexedDB, it was easy - every time I updated data, it was automatically saved to disk. I could do the same with my cache, but writing to IndexedDB for every single update would be be way too slow. My solution was to keep track of which objects in my cache are "dirty" (have changed since the last sync to disk) and then have a function that writes all dirty objects to IndexedDB. Then, this function is called periodically in the background to ensure the cache and disk never fall too far out of sync.

Ultimately, I came up with (IMHO) a pretty decent caching module and started using it everywhere. I started with game simulation, the most CPU intensive part of the codebase. Results were promising - a 50% speedup! But as I converted more and more of the UI to my cache, that 50% speedup gradually disappeared. Even worse, the UI became less and less responsive to the point where it actually felt worse than it did originally! Hey, what gives?

I think the problem was that JavaScript is single threaded. So while IndexedDB could do a lot of work off the main thread, my cache could not. Instead, when my cache was doing stuff, it would block the UI from updating, making it appear very slow and horrible.

This was not good. I had just spent a lot of time working on this thing, and it just made things worse! But did I give up? No! On to phase 2, leveraging Workers!

By "Workers" I mean three different things: Web Workers, Shared Workers, and Service Workers. They all allow you to run JavaScript code off the main thread, which could potentially solve the problem with my cache. And they all are a bit different:

Based on that, I started with a Web Worker, because it's simple and globally supported. However, Web Workers do not make it easy to support multi-tab play, and that was originally the whole point of all this, right? So my plan was to get it working in a Web Worker, and then add support for Shared Workers in browsers that support it.

This also required a ton of work! Because Basketball GM runs entirely client-side in your browser, it was easy for some bad habits to creep in. There was fairly tight coupling between the UI (code to display pages, handle links, update UI) and the backend (game logic, data manipulation). But I wanted to run the backend in a Worker, which required entirely splitting the UI and backend, and defining an API for them to communicate. I wrote a nifty little library called promise-worker-bi to make communication easier. But there was a serious technical problem, a more troubling incantation of a problem I had dealt with in the past: IndexedDB and Promises don't play nice.

Let's do some more technical digression. As mentioned above, my cache still ultimately saved game data to IndexedDB. IndexedDB has a ridiculously horrible and painful API which can only be rescued by wrapping it in Promises, which is the new standard way of handling asynchronous operations (IndexedDB has a crazy amount of asynchronous stuff going on). I wrote a library called backboard which does a decent job of this, and I've been using it in Basketball GM for a while.

However, it doesn't work inside a Worker! Well, it does in Chrome, but not in Firefox! Why? Because Promises in Firefox don't play nice with IndexedDB. Previously I had hacked around this by using a third party Promise implementation rather than native Promises. However the tricks that these third party Promise implementations use to play nice with IndexedDB do not work inside Workers! Fuck.

I spent a while trying to figure out a nice way around this, but there wasn't one. Fortunately, the cache meant that I didn't actually have that much code doing complicated stuff with IndexedDB. So I very carefully went over all of my database code and ensured that it didn't mix IndexedDB and Promises.

Eventually I got it to run. I decided to do a quick benchmark and see if now, after all this, it actually has decent performance. I was optimistically hoping to recover that 50% speedup I initially saw after implementing the cache. Instead, I saw a 10x increase in performance! Fuck. I was really excited. I made a vague post on /r/BasketballGM entitled HOLY SHIT YOU GUYS HAVE NO IDEA WHAT I JUST ACCOMPLISHED and celebrated my accomplishment by taking my girl out to McDonald's where I got a well-deserved Grand Mac and she got a less well-deserved Mac Jr.

But wait, how was that possible? 10x performance boosts don't just fall out of thin air. I think a big part of the answer is that I (like many others) assumed that IndexedDB being asynchronous meant that it would not interfere with the UI, that I could do IndexedDB stuff in the main thread without impeding performance. But I never actually tested that. I did notice that Nolan Lawson showed it was actually not true, but I still wasn't expecting a 10x performance increase! Moral of the story: if you are doing IndexedDB, put that shit in a Worker! Even if you have to suffer through IndexedDB/Promise incompatibilities. 10x is worth it.

Around this time, there was even more good news. Safari has long had very serious issues with IndexedDB, so Basketball GM never ran in Safari. And because Apple is evil and won't let anyone else release a browser on iOS (no, Chrome is not real Chrome on iOS, it's just Safari with a different UI), Basketball GM has never worked on iPhones and iPads. But then Apple released Safari 10.0.3, which was good enough to partially play Basketball GM. It would let you get up to the playoffs, at least. But on my development version, it actually worked really well! Sure it was a bit slower than other browsers, but finally there were no weird errors! So I figured I was going to release a new version of Basketball GM that (1) has fixed Chrome multi-tab support; (2) is way faster; and (3) works in Safari. I released a beta, to much critical acclaim.

But wait, I hadn't actually fixed multi-tab support. The beta only let you open a league in one tab, which kind of sucked. My plan for that was to move from a Web Worker to a Shared Worker, but that wouldn't work in Safari because Safari doesn't support Shared Workers. Crap. I decided to implement Shared Worker support, but keep the Web Worker mode around as a fallback. I put a lot more work into promise-worker-bi to make it seamlessly work with either a Shared Worker or a Web Worker. I rewrote a lot of backend code that made the assumption that it was only talking to one instance of the UI. Humorously, I introduced a new limitation: instead of letting you only open one tab for a league, you could only open one league (but in as many tabs as you want). I figured that is a more palatable constraint, and it would be a lot of work to make the backend support having multiple leagues loaded at the same time.

And all this worked! The Shared Worker did run a bit slower than the Web Worker, for whatever reason. But it was still way faster than before. And multi-tab play was back, even in Chrome! Because the Shared Worker is shared by all tabs, the whole "simulation running in a background tab" thing never happens. It's always in the active tab!

I released another beta for people to test. By the way, I really appreciate all the testing people did, a lot of bugs were found in the beta. Special shout out to the homie Jerick Don San Juan for finding the most.

While I was waiting for people to test it, some other stuff happened:

Some people on the subreddit asked for table filtering, so I added it. It was actually very easy to add, and it was purely a UI thing so it didn't interfere with any of the other in-progress work.

I got rid of the jQuery dependency! Basketball GM started out as a horrible mess of spaghetti code because I didn't know how the hell to write JavaScript (in my defense, basically nobody did back then). So of course I used jQuery everywhere. By now, I had gotten rid of it everywhere except two places: AJAX requests and roster drag-and-drop reordering. Since jQuery doesn't run in a Worker and some AJAX requests happened in the backend, I replaced it with the new Fetch API. So all that was left was drag-and-drop roster sorting. There is a module called React DnD that in theory could replace jQuery for that purpose, but when I tried it in the past, I found it to be horribly overengineered and complicated. Now, there is an alternative called react-sortable-hoc which is actually pretty awesome. I switched to that, and BAM! no more jQuery! I guess it doesn't really matter from an end user perspective, other than making the initial load a bit faster. But it feels really nice to me!

And then, Apple. Safari 10.1 was released, which boasted much improved IndexedDB support. I was excited! Are the bugs really all gone? Is it going to be as fast as Chrome and Firefox? Initial reports were that it was good enough to fully run the old version of Basketball GM. But what about the beta? After forcing my girlfriend to update her iPhone, I eagerly waited to see the result. And the result was... fuck, a hard crash of the browser? Are you fucking kidding me? Jesus, Apple, get your shit together!

Well I wasn't about to hold up the 4.0 release just for Apple, so I said fuck it and released version 4.0 on April 1, an anti April Fool's Day joke. The real joke is that, after several years of Safari being shitty in various ways, there were actually a couple weeks where it worked either on the beta (Safari 10.0.3) or on the old version of Basketball GM (Safari 10.1). But now it's back to not working. What else is new? So the race remains - will Apple or Microsoft be first to make a browser good enough to consistently run Basketball GM? Time will tell...

If you somehow made it to the end of this post, go check out Basketball GM on GitHub. Play around with the code. Contributors are always welcome. At least give me a damn star!