Now that the competition has finished, I wanted to take some time to discuss how I came up with the concept of my flip and write style game The Encroaching Darkness, how I designed it, the problems I had to solve, and how I executed the idea.

But first, if you haven't played the game yet you should head over to the competition site and play it a few times. It's free to play in the browser and only takes a few minutes. I'll wait.

Finished? Great! Let's begin.

How I Came Up With The Concept

This years theme for the competition was Triskaidekaphobia, the fear of the number 13. This was the 13th year of the competition so it was a very fitting theme.

As I thought about what game I could make that would incorporate the theme and how limited my time would be this year to participate, I decided I wanted to try making a small game that could easily be a board game. I decided that I wanted to try to make a city building style game as well. I seem to be enjoying those lately since I made Osteopolis for last years competition.

I started by looking at other games that I enjoy that would be similar to the style I wanted to make. I looked at Everdell, San Juan, Roll Through the Ages, Era: Medieval Age, Against the Storm, Frostpunk, ISLANDERS, Foundation, and Tiny Islands.

I made a list of the things I liked about the games and could maybe incorporate into my own game. I've always wanted to make a game that was like Tiny Islands in both scope and size, so I thought I would start with a game about placing buildings on a grid.

From city builders like Foundation and Frostpunk I looked at how people had needs that you had to meet. From Against the Storm I looked at how it played with buildings being randomly given to the player. From Era: Medieval Age and Roll Through the Ages I looked at the disasters and gaining resources through dice rolls.

From San Juan I looked at how the cards were both buildings and the resources needed to build them. Lastly from ISLANDERS and Tiny Islands I looked at building placement requirements and scoring based on surrounding buildings and features.

With all these things I came up with an initial idea of making a survival style city building (another style of game I like since I made Ravaged Space for the Australian Bushfire Charity Jam). I wanted a game that had the same type of constant threat mechanic like Frostpunk and its cold. Something that started as a minor threat, but not too difficult to manage, but that would quickly escalate into a serious problem that you had to plan how to deal with.

I decided to incorporate the fear part of the theme and thought about how fear can be overwhelming. This lead to the idea to use darkness as the mechanic and that it would spread or grow over time to start swallowing up the tiles on the board.

Designing the Game

With the main threat mechanic and style of game decided on, I next wanted to come up with how the game would be played. My first idea was that you would place houses on the board and each house would have needs, like food and water. You would then need to place down other buildings that satisfied these needs.

I also wanted a sort of resource mechanic that wasn't number based. After all any number that counted up would eventually reach 13, which I wanted to avoid due to the theme. Games like Era: Medieval Age restrict how many of a resource you can have, but I didn't want to track resources as that would add more noise to the game than I wanted.

I decided to try an idea where certain buildings were unavailable until you had built another building first. For example you couldn't build a building that required wood without first building the building that produced the wood. That lead to the lumber mill and stone mason buildings to unlock wood and stone buildings.

I wanted to have the buildings that come up be random, similar to Tiny Islands and Against the Storm. I came up with the idea to incorporate the number 13 part of the theme by assigning each building a value, and if the total value of the drawn cards was 13 or more then that would be how the darkness would spread.

I also wanted some sort of push your luck mechanic so decided that the number of houses would dictate how many buildings would be dealt each round. By building more houses to score more points, you also increased the chance of spreading the darkness.

That was enough of the game to start paper prototyping. I played a few games on paper and the concept was interesting. I had someone else try it out as well, and then coded up a quick prototype that I shared with the Js13k community. For the prototype I simplified everything down to just what I wanted to test, which was drawing cards and what happens when you draw over 13 in value.

Those who played the prototype thought the concept was interesting, so I moved forward with the idea and started fleshing out the game more.

I worked on making buildings score via adjacency to other buildings, and made buildings only satisfy the needs of houses based on being adjacent. I worked on what buildings to have and came up with a list of 8 I thought might work and how they would score.

• Houses would gain you lots of points but also have needs of water, food, and light. Not satisfying these needs would lose you points
• Wells would provide water but only to adjacent houses
• Farms would provide food to any house on the map, but only up to 2 houses per farm
• Lumber mills would allow you to build buildings that required wood
• Stone masons would allow you to build buildings that required stone
• Churches required a lumber mill before they're available and would help mitigate the problem of drawing too many cards by reducing the total value the cards by 3
• Builder Huts required a lumber mill before they're available and would let you build a 2nd building each round
• Light Towers required a stone mason before they're available and would provide light to any nearby houses. They would also push back the darkness, preventing it from spreading into adjacent tiles. Light towers are there to help mitigate the darkness spreading where you don't want it to

I had other ideas for buildings that could be used, such as walls, but decided they made the game more complex than I wanted.

I also worked on figuring out the size of board I wanted the game to play on and how the darkness would start on the board and spread. I started with a 10x10 board (for no particular reason) and tried to think about how to randomly place the darkness. I thought it would be interesting if the darkness could start on any tile that was a multiple of 13, in any direction of row and column. Then I would pick 13 of them at random for the starting placement.

When the darkness spread the game would choose a random darkness tile and have it spread into one of its adjacent tiles.

I did a lot more paper prototyping with others, trying to figure out how to score buildings that felt good. I initially had a lot of the buildings give both positive and negative points depending on placement, similar to ISLANDERS. I went through many iterations of changing the scoring. I eventually decided to remove all of the negative point scoring as it made things too complicated.

I also decided that a 10x10 board was too small to fit everything, especially if you wanted to place buildings a few tiles away from the darkness. So I increased the board size to 11x11 to give more breathing room.

After paper prototyping a bunch, I updated the online version and sent out another round of prototyping to the community.

Finding the Fun

It was during this time that I was feeling that the game wasn't fun to play. There were a few things that contributed to that feeling.

The first was that it was too easy to play conservatively and never draw more than 2 cards the entire game. This would almost guarantee that you would never draw more than 13 total value so the darkness would never spread. I wanted the darkness to be a constant threat so I didn't want the players to feel like it was more of an inconvenience.

The second was that the way buildings worked and scored wasn't working. The lumber mill and stone mason were no longer needed after you built them once, so when they showed up again it felt like a wasted draw.

Houses were also problematic. Since they would increase how many cards you would draw per round no one wanted to build more of them since it would increase the chance for the darkness to spread.

The third and more major problem was that it wasn't interesting to place the buildings. You could always place your buildings in an optimal way and the way buildings scored wasn't in and of itself providing enough strategy and fun.

With a few weeks left of the competition I needed to figure these things out.

Making the Darkness more Threatening

The first thing I decided to tackle was the darkness. I tried a few different approaches to make the darkness more threatening.

Since the darkness was spreading too slowly I decided to spread it multiple times every time the total value of the cards was 13 or more. That didn't work as it caused the darkness to get out of hand really quickly.

I next tried making the darkness spread to every adjacent tile instead of just 1. This made it spread too quickly when combined with spreading multiple times, so I reverted to just spreading it once every time.

That fixed the problem with how the darkness spread, but it still didn't address the problem of players playing conservatively. I decided to try having the darkness spread at the end of every round. Having a negative effect happen at the end of every turn is a popular mechanic in coop style board games such as Pandemic and Flash Point.

Having the darkness spread every turn made all the difference to how threatening the darkness was. Now players had no choice about when it spread and instead had to plan how they wouldn't spread it further.

The last thing I did was encourage the darkness to spread as much as it could every time. The problem I was finding was that half way through the game the darkness would merge into a big glob and the majority of darkness tiles would then only have 1 or 2 other tiles it could spread into.

I didn't like how it felt when the darkness barely spread, so I programmed it to sort the darkness tiles by how many neighboring tiles it could spread into, then biased the random number generator to favor tiles that had the greatest number of spreadable tiles. This helped the darkness feel constantly threatening rather than tapering off near the end game.

Hindering the Optimal Play

Next up was figuring out how to stop players from playing optimally every game. In Tiny Islands the tiles have restrictions on where they can be played, restricted to a certain row, column, or area. I didn't want to copy Tiny Islands mechanic so I tried to think of something I could do.

After a week of pondering on it I had the thought of restricting building placement on the board using their values. This made me think of the game Sodoku where you play in a 9x9 grid and each of the numbers 1-9 can only show up in any row, column, or 3x3 group exactly once.

I tried implementing a similar concept to my game where each building could only be placed in any row, column, or 3x3 group exactly once, but it made the game too restrictive in building placement. I looked at other games similar to Sodoku to get more ideas on how to play with numbers, such as Kakuro and Futoshiki, but I wasn't able to come up with anything that worked.

While looking up similar games I stumbled upon Jigsaw Sudoku, which uses irregular shapes for the area bounds rather than a 3x3 group. This made me think about having my buildings take up an area rather than just be a 1x1 tile. I immediately thought of using Tetris like pieces for the buildings, and quickly prototyped a version of the game using 3 piece tetrominoes. After the first game I knew I had what I wanted.

I also kept the concept of Sokoban row and column rules, but instead of restricting play it instead counted the values of the buildings in the same row and column and if they totaled 13 or more the darkness would spread.

Changing the Way Buildings Worked

To try to fix the buildings, I tried changing how lumber mills and stone masons worked. Instead of automatically unlocking the church and light tower, I decided to make each building have a percent chance of being drawn. The lumber mill and stone mason would then increase the percent chance of the church and light tower. That way you would be incentivized to build them more than once.

However this change didn't seem to work. Players would try to build stone masons to get light towers, but when light towers didn't show up the players felt like the mechanic wasn't working. I tried adjusting the percent increase many times but in the end nothing was working.

I finally decided to just drop the mechanic of locking out the church and light house and instead just made every building equally likely to be drawn.

The farm and well also suffered from the same problem that once you had enough to satisfy all the needs of your houses, you didn't really want to build more of them. After some time I decided to remove the needs system completely. This meant that houses wouldn't require needs and buildings wouldn't satisfy anything.

Lastly the church's mechanic of reducing the total value of the buildings was too complex so I removed it, and I removed the builder hut as I no longer felt I needed to give players a way to build multiple times per round.

Improving the Scoring

With all the changes to buildings and placement, I also needed to fix how the buildings scored.

To improve the scoring I looked at games like Cartographers, Era: Medieval Age, and Carcassonne. I wanted to make how buildings scored be unique and interesting and not just always have it score based on being adjacent to other things.

One of the first changes I made was to replace the well with a lake since they didn't need to provide water to houses. I figured lakes are more interesting when they are surrounded by many features, so I decided to score it like the Monastery from Carcassonne where it gain a point for every nearby building or feature. This made the lake a building you wanted to cluster around other things.

For the lumber mill and stone mason I added trees and mountains to the board and chose to make them gain points based on being nearby them (respectively). Unfortunately this made them essentially function the exact same, so I'm not entirely happy with it but I was running out of time at this point so left it as is.

I thought houses would like to be clustered together, so chose to score them based on clusters of adjacent houses. This is similar to how the Forests work in Tiny Islands and Villages in Cartographers.

Farms benefit from being larger (since they can feed more people) so for a different way to score I decided to use the area of the farm shape for the scoring. The more area the farm has the more it scores. This encourages you to place the larger tiles instead of always choosing smaller ones to fit better.

For the church and light tower, again due to lack of time, I just took some scoring concepts from Tiny Islands. Churches should be placed far away from the darkness (similar to boats) and light towers shouldn't be in the same row or column as another light tower (similar to waves).

Finishing Touches

With the game now settled I tested it a few times with others and everyone loved it.

With only a few days left before the deadline, it was time to finish the last two missing parts: art and final scoring. Up until this point I never had implemented the final scoring as I was focused on the main game mechanics.

I started by looking for images to use for the buildings. I looked at a few of my favorite sites to grab assets from: OpenGameArt, Flaticon, Game-icons.net, and Kenney. I couldn't find icons in the first 3 sites, but I stumbled upon Kenney's Cartographer Pack which was the style I was hoping for and had all the buildings I needed.

I knew that the game would be confusing to understand at first, and that I didn't have enough time to try to create a tutorial or explain the game any better than my initial prototype UI (which was a mess). I needed a way to make sure that the players understood how buildings scored at least at the end so that they would be encouraged to play again.

I once again took inspiration from Tiny Islands and used its scoring animation to teach the player how the buildings worked. It worked out really well and I was able to get it working a few hours before the deadline.

Game Reception

The game has been really well received during the competition. Players have commented that it's very replayable and fun. As I suspected the game takes players a few times before it really clicks, but it plays quickly enough that it hopefully hasn't deterred anyone from playing more than once.

The UI is still a mess since I ran out of time so I probably won't score very high in that category. But overall I'm extremely pleased with the game and how it turned out.

After the competition I plan to release a post-compo version of the game to itch.io. As always it'll focus on improving the UI and adding accessibility features. I plan to make it accessible to screen readers so players with limited to no vision can play it. I have an idea of how I'm going to make that work, but it'll take some testing to figure out how best to inform the player about the shapes of pieces.

# CLI works as expected
npx prettier --write path_to_file

// Node API wasn't formatting correctly
const prettier = require('prettier');
prettier.format(code, ...options);

After a lot of trial and error, I was finally able to figure out the required steps in order to get it to work.

First, using the Node API requires that you pass the parser option. I had always struggled to figure out which parser to use as Prettier doesn't seem to list the defaults (especially when trying to format JSON). It turns out that if you pass the filepath option, Prettier will infer the parser option for you. This wasn't stated clearly enough for me to understand in the docs.

The reason it uses filepath instead of using something like file extension is because the Prettier config file can have overrides that are triggered based on the filepath.

prettier.format(code, {
  filepath: 'path_to_file'
});

The next thing I had to do was figure out how to import the Prettier config. I would have assumed the format function would load it automatically, but that was not the case. Instead we have to load it ourselves and pass it as options into the function using the resolveConfig function.

const filepath = 'path_to_file';
const config = prettier.resolveConfig.sync(filepath);
prettier.format(code, {
  filepath,
  ...config
});

Lastly, in order to correctly format JSON you have to stringify it first. Not only that, but you also might need to use the space option when you stringify in order for Prettier to output newlines correctly. Otherwise Prettier will try to put object properties on a single line if they don't exceed the line width setting.

const filepath = 'path_to_file';
const config = prettier.resolveConfig.sync(filepath);
const code = JSON.stringify(data, null, 2);
prettier.format(code, {
  filepath,
  ...config
});

With that, I was able to get the API and the CLI to be consistent in how the code was formatted.

So for example, if we wanted to run the function add and capture the output to the variable value, we would write:

function add() {
  echo $(($1 + $2))
}

value=$(add 5 3)
echo $value  # 8

This worked great until I wanted to add verbose log output to the function I was calling. This proved a difficult challenge since adding additional output would be saved to the variable, which is not what I wanted.

verbose=1

function add() {
  result=$(($1 + $2))
  if [[ "$verbose" -eq 1 ]]; then
    echo "adding $1 and $2 for a result of $result"
  fi

  echo $result
}

value=$(add 5 3)
echo $value  # adding 5 and 3 for a result of 8 8

I tried a lot of different ideas on how to solve the problem, from taking the last line of the output to using the tee command. Everything I tried never really worked the way I wanted. Either the logs would display everything (including the last line which wasn't necessary) or output in the wrong order (especially with error messages sending to stderr).

Eventually I stumbled upon this stackoverflow question which let me do exactly what I wanted.

The solution is use a new file descriptor to send the output of the verbose log to something other than stdout. However, using a new file descriptor will result in an error if the calling script doesn't define how to use it. Normally you would do this when you call the command. However, sending all the output from the new file descriptor to stdout would get us back to square one and all the logs would still end up in the captured variable.

function add() {
  result=$(($1 + $2))
  if [[ "$verbose" -eq 1 ]]; then
    # Send output to file descriptor 3
    >&3 echo "adding $1 and $2 for a result of $result"
  fi

  echo $result
}

# Notice that file descriptor 3 is being redirected to stdout (file descriptor 1)
value=$(add 5 3 3>&1)
echo $value  # adding 5 and 3 for a result of 8 8

Instead what we need to do is use the exec command to tell bash to redirect all output from the new file descriptor to stdout for all commands. Doing this allows us to output the verbose logs to stdout without adding them to the captured variable.

exec 3>&1
verbose=1

function add() {
  result=$(($1 + $2))
  if [[ "$verbose" -eq 1 ]]; then
    # Send output to file descriptor 3
    >&3 echo "adding $1 and $2 for a result of $result"
  fi

  echo $result
}

value=$(add 5 3)
echo $value  # 8

Running this would produce the desired result:

$ sh script.sh
adding 5 and 3 for a result of 8
8

less content about how to pass tech interviews. more content about how to conduct tech interviews.

I've been conducting a lot of technical interviews recently, so inspired by Angie's tweet I wanted to write about my teams process for conducting a technical interview. But before I talk about the interview process itself I want to give some context to the role the interviewees are applying for.

My team is responsible for maintaining the accessibility testing engine axe-core, and axe-core-npm which are integrations of axe-core into various frameworks and technologies. Since our team works with so many different frameworks, we expect the candidate to be willing to learn frameworks they may not be familiar with, and sometimes even become subject matter experts on them for the team.

We're also a fully remote team which means the candidate will be working by themselves for good portions of the day. This means we expect the candidate to be able to understand how to learn on their own as well as know when to ask for help. We do a lot of pairing on the team and are always willing to jump on Zoom to discuss a problem or even be a rubber duck.

We've made sure to document these requirements as part of the job description.

The Pre-interview Assignment

Before a technical interview takes place, we give the candidate a small take-home pre-interview assignment that they'll bring to the interview. The assignment focuses on configuring one of our open-source APIs to do a small task. We've made sure the task is neither large nor time consuming, and we allow the candidate a few days to complete it before the interview.

The purpose of the assignment is to ensure that the candidate is willing to learn something new (most users have not configured our API in this manner) and understands how to read at our public documentation to find the answer. It also serves as an introduction to our open-source code as the technical interview will leverage that knowledge.

The Technical Interview

My team fully understands that traditional technical interviews do not work well. We're also a remote team so we can't do traditional in-person interviews anyway. We've spent a lot of time trying to come up with an alternative method that can help us unbiasedly assess the technical ability of a candidate.

To start, we use a similar process to Lara Hogans Onsite Interview Template. We've created a list of signals that we are looking for in a candidate based on the job requirements listed in the job posting. Using these signals, we created an evaluation form that we can fill out during, or immediately after, the interview. The evaluation form is essentially a list of questions about the candidate that relate to the signals. This form helps us see at a glance how well the candidate did and helps us evaluate one candidate over another.

We've even made sure that what we evaluate for is adjusted based on the position. We expect more from senior developer candidates than mid level candidates and have created separate evaluation forms that take into account those differences. We've been really pleased with how it's turned out.

The technical interview itself is quite unique. We don't ask any technical or algorithmic questions. Instead we essentially do a pairing session (cameras off) with the candidate and ask them to work with us to solve a problem.

We provide a small, fully working boilerplate project (with tests) that has the main part of the program stubbed out. We also provide a README with the problem defined and a list of requirements for the project. The project is similar to something we would do on the job, which gives the candidate a good feel for the types of things they'll be working on if they were to join the team.

We let the candidate drive the coding session while sharing their screen. We are there to support them, answer their questions, and help them work out the solution to the problem. We very much allow and encourage looking up answers, using Stack Overflow, reading the documentation, etc. After all, we don't care so much what you know off the top of your head but more about how you go about finding answers.

The requirements are set up in such a way that there are more things to do in the project than the candidate would have time to complete in the interview. This way we can tell them that we're only interested in how they go about solving the problem, not how much they can solve.

Because this is a non-standard approach to a technical interview, we try to be very clear upfront about it. The day before the interview we send out an email to the candidate telling them what they can expect from the interview. We try to be very clear about what we'll be doing in the interview, what they can do and lookup, and the goals of the interview.

We hope that by doing this (allowing looking up answers, not worrying about how much they do, telling them ahead of time our expectations), the candidate feels less stressed over the interview and can be more comfortable during it.

Rational of the Technical Interview

There are many reasons why we do our technical interviews this way instead of say, a full take-home assignment.

First, we've discovered that doing a pairing session with a candidate can help us see their potential. Potential is something that you can't test for nor can see very easily in the final product. We once had a mid-level candidate read the requirements document and then tell us how they thought the program should be structured to make it work. Without writing a single line of code, we could tell that the candidate had a good grasp of technical design. That's not something we could have known otherwise.

Second, we want to see how the user goes about learning a new codebase. The ability to read an unfamiliar code base and understand how it works is extremely important for our team. By being able to watch them learn the code, we can see into their learning process. A side benefit is that by seeing how they learn, we can adjust the onboarding process to better match their learning style.

Lastly, we want to get a feeling for how the candidate would be to work with. Do they respond well to suggestions? How is their personality while working on a problem? How much do their try to solve the problem on their own vs having us drive the solution?

Of course, this process may not work for every team nor every candidate. Overall we feel we have succeeded in our goal to create a better technical interview process that works well for our teams needs.

The main problem I had was that there are lots of different tools and ways to package an app. There's electron-forge, election-packager, and election-builder. Each one claims to be either a "complete tool" or "complete solution" to create, package, and distribute an Electron app. Each does a slightly different thing and figuring out which one to use to do what I wanted was difficult.

This guide aims to help you navigate these different tools and how to use them so you can choose the right one for your needs. It will also try to help you avoid the pitfalls I stumbled into while learning them.

What this guide does not cover are the various ways to integrate Electron into different frameworks, for example Wepback. This guide will only cover Electron itself and its various tools.

So without further ado, let's dive in.

Table of Contents

• Building An Electron App
  • Communicating with the Main Process
  • Secure Communication
  • Opening DevTools on Windows
  • Building on WSL
  • Other Problems
• Packaging an Electron App
  • Prerequisites for Packaging Windows Apps on Mac
  • electron-forge
  • electron-packager
  • electron-builder
  • Which Packaging Tool to Use
  • Packaging on WSL
    • No Audio in Electron App
    • Mac Package Didn't Work

Building An Electron App

Before you can package an Electron app, you first must build one. I found building an app to be the easiest part of the whole process. The Electron Quick Start Guide was indeed quick and I was able to get my app booted in Electron following their guide without any problems.

However, problems arose as I started trying to integrated Electron APIs into my app. Below are some common problems I ran into and their solutions.

Communicating with the Main Process

As far as I could tell, the Electron docs do not cover communicating between the app and the main process.

The most common way to do that is to use the ipcRenderer to send and receive messages. For example, if you wanted to send a command to tell the app to quit, you would do the following:

// inside the main process (e.g. main.js)
const { app, BrowserWindow, ipcMain } = require('electron');

function createWindow () {
  const win = new BrowserWindow({
    webPreferences: {
      nodeIntegration: true
    }
  });

  win.loadFile('index.html')
}

app.whenReady().then(createWindow);

ipcMain.on('quit-app', () => app.quit());

// inside the app (e.g. index.html)
const { ipcRenderer } = require('electron');
ipcRenderer.send('quit-app');

Notice that you use the ipcRenderer object in the app to send the message but the ipcMain object to listen for it. Also for this to work you must enable webPreferences.nodeIntegration when you create the browser window, otherwise you cannot use require inside of the app.

However, enabling nodeIntegration is actually a security risk. Allowing your app to not only be able to require arbitrary code but also allow that code to communicate and send arbitrary commands to your main process is dangerous.

Secure Communication

There is a secure way to handle communicating with your main process. It's buried deep in an Electron issue not even related to a security problem so it can be very easy to miss.

The gist of the solution is to limit how much access your app has to the ipcRenderer so it can only send and receive very specific commands all while disabling nodeIntegration and other attack vectors. All credit to reZach for the following solution.

// inside the main process (e.g. main.js)
const { app, BrowserWindow, ipcMain } = require('electron');

function createWindow () {
  const win = new BrowserWindow({
    webPreferences: {
      nodeIntegration: false, // is default value after Electron v5
      contextIsolation: true, // protect against prototype pollution
      enableRemoteModule: false, // turn off remote
      preload: path.join(__dirname, 'preload.js') // use a preload script
    }
  });

  win.loadFile('index.html')
}

app.whenReady().then(createWindow);

ipcMain.on('toMain', (event, command) => {
  // process specific commands
});

// preload.js
const { contextBridge, ipcRenderer } = require('electron');

// Expose protected methods that allow the renderer process to use
// the ipcRenderer without exposing the entire object
contextBridge.exposeInMainWorld(
  'api', {
    send: (channel, data) => {
      // allow only specific channels
      const validChannels = ['toMain'];
      if (validChannels.includes(channel)) {
        ipcRenderer.send(channel, data);
      }
    },
    receive: (channel, func) => {
      const validChannels = ['fromMain'];
      if (validChannels.includes(channel)) {
        // Deliberately strip event as it includes `sender` 
        ipcRenderer.on(channel, (event, ...args) => func(...args));
      }
    }
  }
);

// inside the app (e.g. index.html)
window.api.send('quit-app');

If you'd like to do even more to secure your app, reZach created a secure-electron-template repo that you can take from.

Opening DevTools on Windows

While developing and testing your Electron app, it's handy to be able to open the DevTools and inspect the current state or just add breakpoints for debugging.

The easiest way to open the DevTools is to start the app with them opened using webContents.openDevTools(). The function also takes an options argument that lets you define how to open them.

// inside the main process (e.g. main.js)
const { app, BrowserWindow } = require('electron');

function createWindow () {
  const win = new BrowserWindow();
  win.webContents.openDevTools();
}

app.whenReady().then(createWindow);

Unfortunately, although this works fine on Mac, it does not work for Windows.

Luckily, there's an issue open in Electron which has a work around for the problem. The solution is to use webContents.setDevToolsWebContents() and a second browser window set to open the DevTools. All credit to warrenseine for the following solution.

// inside the main process (e.g. main.js)
const { app, BrowserWindow } = require('electron');

function createWindow () {
  const win = new BrowserWindow();
  const devtools = new BrowserWindow();

  win.webContents.setDevToolsWebContents(devtools.webContents);
  win.webContents.openDevTools({ mode: 'detach' });
}

app.whenReady().then(createWindow);

Building on WSL

Most of the time I develop using Mac, but since I was building an Electron app I wanted to test if my app still worked on Windows when built. Using the Windows Subsystem for Linux (WSL) I tried to run the app using npm start.

Unfortunately I couldn't even start the app. Every time I would run npm run start I would get an error stating that a missing shared library couldn't be located.

Error while loading shared libraries: libxshmfence.so.1: cannot open shared object file: No such file or directory

For the longest time I couldn't figure out what to do to solve this. Then I discovered the answer buried in the electron-forge docs (of all places). It turns out you need to reinstall node_modules and tell npm to use win32 platform prebuilt binaries.

rm -r node_modules
npm install --platform=win32

Once installed, you can now run npm run start and the Electron app should start.

However once started the app wasn't running. Looking at the Network tab it seems all requests but for the first few were Pending indefinitely. I wasn't sure how to proceed after that and couldn't find any information online. I even tried upgrading to use WSL2 (as I was still on 1) but that didn't fix the problem.

The only answer I was able to find was to instead install node and electron on Windows itself and then start the electron app from WSL. Not the best solution, but it does seem to work.

Other Problems

These were the problems I ran into, but for more problems and their solutions read 4 must-know tips for building cross platform Electron apps.

Packaging an Electron App

As mentioned before, there are 3 different tools to package an Electron app: electron-forge, electron-packager, and electron-builder. As we look at each one we'll be trying to package an app for Mac, Windows, and Linux.

The Electron Quick Start Guide recommends installing electron-forge to handle packaging so we'll start with that one.

Prerequisites for Packaging Windows Apps on Mac

If you plan to package your application for Windows on a Mac, you'll first need to install Wine. Wine is program that lets non-Windows operating systems run Windows software. Electron packaging tools will use Windows APIs to build the Windows package.

To install Wine on Mac, follow the How to install/about wine on mac guide.

electron-forge

First install electron-forge into your project and run the import command.

npm install --save-dev @electron-forge/cli
npx electron-forge import

The import command will configure your app to use electron-forge and add a few package scripts and a config property to your package.json.

"scripts": {
  "start": "electron-forge start",
  "package": "electron-forge package",
  "make": "electron-forge make"
},
"config": {
  "forge": {
    "packagerConfig": {},
    "makers": [
      {
        "name": "@electron-forge/maker-squirrel",
        "config": {
          "name": "<appname>"
        }
      },
      {
        "name": "@electron-forge/maker-zip",
        "platforms": [
          "darwin"
        ]
      },
      {
        "name": "@electron-forge/maker-deb",
        "config": {}
      },
      {
        "name": "@electron-forge/maker-rpm",
        "config": {}
      }
    ]
  }
}

Important Note: The scripts electron-forge creates will override any scripts of the same name that are already defined. So if you have a start, package, or make script already then they will be overridden by electron-forge.

Once set up, you can run npm run make to build a Mac package and a zip file containing the Mac package of your app (if on Mac). However, it will not build a Windows or Linux package.

At this point I wasn't sure how to build a Windows or Linux package using electron-forge. Even though the default config provided by the import command sets up a Windows maker using maker-squirrel, it doesn't produce one. Nor does it produce a Linux package using maker-deb.

I thought maybe the packagerConfig needed to be told to build them. Trying to set "all": true so that electron-packager would build for all platforms didn't work as I got an error from electron-forge saying it wasn't supported.

Error: config.forge.packagerConfig.all is not supported by Electron Forge

I next tried to set platforms to ['darwin', 'linux', 'win32'] on the packagerConfig object but that didn't do anything as only the Mac application was built again.

Lastly, I noticed that you could pass the make cli command options to specify the platform. I tried passing win32 and this somewhat worked as it tried to build a squirrel package. Unfortunately it also produced a very unhelpful error about not being able to spawn mono.

npm run make -- --platform win32
...
Making for target: squirrel - On platform: win32 - For arch: x64

An unhandled error has occurred inside Forge:
An error occured while making for target: squirrel
spawn mono ENOENT
Error: spawn mono ENOENT

It would seem that electron-forge cannot package for other platforms (their docs even say as much). As such, my opinion is that using electron-forge is not a solution for cross-platform packaging.

Target platform to make for, please note you normally can only target platform X from platform X

electron-packager

The next tool is election-packager. Electron-packager is used by electron-forge to build cross platform packages that the make script then uses to build a package.

First install electron-packager.

npm install --save-dev electron-packager

Once installed, you can build for all platforms using the --all flag when running the electron-packager cli. You'll also need to make sure to provide icons for each platform package to use. Each platform uses a different extension for the icon: .icns for Mac, .ico for Windows, and .png for Linux.

If you have all three icons in a single directory, you can tell electron-packager to use the directory and it will automatically choose the correct icon to use for the package.

npx electron-packager . <appname> --all --icon=path/to/icons/dir

Once run, you should have built packages for each of the three platforms and for each different architecture (a total of eleven packages).

If you don't want all platforms and architectures, you can instead provide the --platform and --arch flags. So if you just wanted Mac x64, and Windows and Linux 32-bit and 64-bit architectures you would do the following:

npx electron-packager . <appname> --platform=darwin,linux,win32 --arch=ia32,x64 --icon=path/to/icons/dir

This will produce a warning about Mac and ia32 not being supported, but it will not stop the build from producing the other combinations.

One thing to note about these packages is that they are what's known as "unpackaged" packages. What that means is that the Windows and Unix executables are not standalone executables. Running them requires additional files that are included in each of their directories.

To distribute these unpackaged packages you'll need to provide your users with the executable and all the other files. For the most part, this isn't an ideal way to distribute an app, but can work in some cases (for example, uploading a game to Steam).

If instead you want to distribute a single standalone executable you'll need to use electron-builder.

electron-builder

Election-builder works in a similar way to electron-forge in that you provide a package.json config object which tells electron-builder which packages to build.

First install electron-builder.

npm install electron-builder

Unlike electron-forge, you'll have to create the build config and scripts manually instead of it being generated for you. The electron-builder Quick Setup Guide provides a sample build config and recommend scripts to setup. It also recommends adding a postinstall script to ensure electron-builder is always up-to-date with your native environment.

"build": {
  "appId": "your.id",
  "mac": {
    "category": "your.app.category.type"
  }
},
"scripts": {
  "pack": "electron-builder --dir",
  "dist": "electron-builder"
},
"postinstall": "electron-builder install-app-deps"

The pack script will build unpackaged versions of your app, just as electron-packager does. The dist script will build the distribution version of your app, which results in a single standalone executable.

In order to build for multiple platforms you'll need to expand the build config to include how to build for your platforms of choice, as well as where to find the icons. The icon option can also take a path to the icon directory where it will automatically select the correct extension to use for the platform.

The electron-builder docs do a good job explaining the options for Mac targets, Windows targets, and Linux targets.

A minimalistic build config could look like the following.

"build": {
  "appId": "your.id",
  "icon": "path/to/icons/dir",
  "mac": {
    "category": "your.app.category.type"
  },
  "win": {
    "target": "portable"
  },
  "linux": {
    "target": "AppImage"
  }
}

Afterwards, you can run npm run dist and it should run. If you haven't set up code signing for your Mac app, the build will let you know but it will package the app without it just fine.

However, just like electron-forge, the dist script only produced a Mac executable (if on Mac). No amount of adjusting the build config would produce a Windows or Linux package.

It turns out that by default the electron-builder command will only build for your current platform. The solution is to provide additional flags to tell it to produce for other platforms. In this case, you want to pass the Mac, Windows, and Linux flags -m, -w, -l (respectively). You can also combine the flags into a single flag -mwl (order doesn't appear to matter).

electron-builder -mwl

With that, electron-builder will produce three packaged executables for Mac, Windows, and Linux. These are standalone packages so each of the executables will be able to run by just opening it (no other files needed).

Which Packaging Tool to Use

Now that we've discussed each of the different tools, which one should you use?

Electron-forge only packages for your current platform, so it doesn't really work for packaging cross platform apps unless you own each of the platforms and don't mind packaging on each of them separately.

Electron-packager does package for each platform, but it only produces unpackaged applications. This means you'll need to provide your users with all the files in each package directory in order for the executables to work.

Electron-builder is my recommendation as it packages for each platform and produces packaged applications. It also can produce unpackaged applications so there's no need to use electron-packager.

Packaging on WSL

Although I didn't run into any problems packaging the app on WSL, I did run into a few problems when trying to run the packaged app.

No Audio in Electron App

First, if you're using WSL1 to package the app, some features may not work.

In my case, my app was using the Web Audio API to play music. However when I booted the app no sound would play. I tried to play audio by instead using an Audio element, but that also didn't work. Using the canPlayType() function for my audio type resulted in "Probably" so that wasn't the cause.

As with the last WSL problem, I couldn't find anything online. However, I did discover that the Windows executable package produced on my Mac would play the audio just fine. I concluded that maybe WSL didn't have any audio drivers and thus electron couldn't package the app with an audio output device enabled.

I was able to solve the problem though by upgrading to WSL2. If you run into a similar problem I would suggest starting there.

Mac Package Didn't Work

When I packaged the Mac application I wanted to see if it would actually work on a Mac. Unfortunately the Mac zip archive that electron-builder produces didn't work. Trying to open the .app file after unzipping it result in a "You do not have permission to open the application" message.

I tried following the solution from this StackExchange issue, but changing the permissions of all files in the app and removing the quarantine bits didn't help. Instead, after I did that and tried to open the app I got a new problem saying that the app couldn't open due to a problem.

Dyld Error Message:
  dyld: Using shared cache: BD3DF5DB-AF3C-3D09-B8D6-4352F71DDBEA
Library not loaded: @rpath/Electron Framework.framework/Electron Framework
  Referenced from: /Users/USER/Downloads/myApp.app/Contents/MacOS/myApp
  Reason: no suitable image found.  Did find:
  /Downloads/myApp.app/Contents/MacOS/../Frameworks/Electron Framework.framework/Electron Framework: file too short
  /Downloads/myApp.app/Contents/MacOS/../Frameworks/Electron Framework.framework/Electron Framework: stat() failed with errno=1

Digging further I found that someone suggested archiving with 7zip rather than zip. Changing the Mac target to 7z produced a 7zip archive which after unzipping was able to open without the previous errors.

"build": {
  "mac": {
    "target": "7z"
  }
}

Of course since the app is unsigned Apple Gatekeeper will prevent you from opening it as it's from an unidentified developer. Code signing doesn't work on non-Mac platforms so the only way to open it is to right click the app and click "Open" from the context menu.

Doing this should allow you to open the app without further issues.

Looking through the Phaser docs I couldn't find an API that would give me that information, so I decided to try to calculate the position myself. After a few hours of trail and error I was finally able to to do it.

My initial attempts at calculating the position involved trying to use the main cameras scroll position to offset the objects world position. However, that didn't work out and it became super complicated trying to take into account when the camera stopped moving at the edges of the world.

I finally just looked at all the camera properties and stumbled upon the worldView property. This property is the current world rectangle that the camera is viewing. Importantly, the x and y position defines the top-left corner of the canvas.

Using this, all we have to do is subtract the game objects world position by the cameras world view position and we have the game objects position relative to the top-left corner of the screen. If your camera is zoomed we'll also need to multiply the final result by the camera zoom.

function getRelativePositionToCanvas(gameObject, camera) {
  return {
    x: (gameObject.x - camera.worldView.x) * camera.zoom,
    y: (gameObject.y - camera.worldView.y) * camera.zoom
  }
}

With the budget in place, I started investigating ways to reduce the file size. We use webpack to bundle axe-core so I used webpack-bundle-analyzer to see a detailed view of how large each file was.

As you may have noticed, there are a few large files that make up our core codebase. The largest of those is a file called valid-langs.js. This particular file is 48 kB minified and 20 kB gzipped. Looking into the file it was a list of all ISO 639-1 and 2 codes that we use to validate the value of the HTML lang attribute.

Thinking about how to reduce the file size, someone from the Google Lighthouse team suggested using a trie data structure. It was a good idea, but I was having trouble figuring out how to store the structure that would result in a smaller file size.

I then remember that there was a music player used for the js13kGames game jam that could store entire songs in less than 1 kB gzipped. They used a technique to store all the information of a song as "a series of nested arrays containing instrument, pattern and sequence data." It turns out JavaScript is really good at compressing nested arrays of numbers.

I figured if they could store songs in such a small size I could use the same technique to store a trie of stings. I discovered that I could store the data as a sequence of nested arrays, where each index represented the letter (a = 0, b = 1, c = 2, etc.). For example, the string aaa could be stored as [[[1]]]. I could then check if the string aaa was valid by converting each letter to its index and navigating the nested arrays. If at any point the index returned null, the string was invalid.

However, this resulted in one and two character strings that started with the same sequence to also be valid. For example, the string a should be invalid but would return valid since there are valid 3 character strings that start with a.

To account for this, I decided to make the letters 1 indexed so that I could use the 0th index to denote if the one or two character string was valid (by padding the end of the string with the ` character). For example, the string aaa and aa are valid, and can be stored as [,[,[1,1]]. Since the string a is turned into a``, it returns invalid as the 2nd nested arrays 0th index is empty.

Doing this to all ISO 639-1 and 2 codes resulted in a total file size of 2 kB gzipped, about 17 kB in savings!

Below is the code for converting an array of strings into a trie of nested arrays and a function to determine if a given string is valid:

const strings = [...];  // array of strings
const enocdedStrings = [];

strings.forEach(str => {
  str = str.padEnd(3, '`');
  let array = enocdedStrings;
  str.split('').forEach((char, i) => {
    // index is 1 indexed
    const index = char.charCodeAt(0) - 96;
    if (i < str.length - 1) {
      array[index] = array[index] || [];
      array = array[index];
    }
    else {
      array[index] = 1;
    }
  });
});

/**
 * Determine if a string is a valid entry in the trie.
 * @param {String} str - String to validate.
 * @return {Boolean}
 */
function isValid(str) {
  let array = enocdedStrings;
  str = str.padEnd(3, '`');

  for (let i = 0; i <= str.length - 1; i++) {
    const index = str.charCodeAt(i) - 96;
    array = array[index];
    if (!array) {
      return false;
    }
  }

  return true;
}

After my research didn't turn up anything, I had an idea that I thought might work.

I remembered that Service Workers could intercept network requests and respond with cached resources. Typically this is used to serve a custom offline page when the user navigates to a page that hasn't been cached yet. But what if we could use that same principle to serve a custom 404 page when the request fails?

There wasn't a lot of information available on doing something that like, but I did find a Google lab article on Service Workers which had an small section on serving a custom 404 from the cache. They didn't list the solution in the article, so I had to open their github repo to find it.

Turns out that it is indeed possible to serve a custom 404 page from a service worker. All it takes is first caching the 404 page and then looking at the response.status of a fetch request. If it's 404, return the cached 404 page.

Now whenever the user enters a URL that isn't found, the Service Worker will intercept the request and return your custom 404. No server required.

const filesToCache = [
  '/',
  '404.html'
];
const staticCacheName = 'pages-cache-v1';

self.addEventListener('install', event => {
  event.waitUntil(
    caches.open(staticCacheName).then(cache => {
      return cache.addAll(filesToCache);
    });
  );
});

self.addEventListener('fetch', event => {
  event.respondWith(
    caches.match(event.request).then(response => {
      // found a cached resource
      if (response) {
        return response;
      }

      // request the non-cached resource
      return fetch(event.request).then(response => {

        // fetch request returned 404, serve custom 404 page
        if (response.status === 404) {
          return caches.match('404.html');
        }
      });
    });
  );
});

Now that the bundle sale has finished, I wanted to take some time to discuss how I came up with the concept of my incremental survival game Ravaged Space, how I designed it, and how I executed the idea.

But first, if you haven't played the game yet you should head over to itch.io and play it a few times. It's free to play in the browser and only takes a few minutes. I'll wait.

Finished? Great! Let's begin.

How I Came Up With The Concept

When I first heard about the game jam, my first idea wasn't Ravaged Space.

I had just heard the news story about how Wombats were saving other animals during the fires by sharing their burrows. I thought it'd be easy to create a game about a Wombat saving other animals from fires.

However, I wasn't really interested in the concept. I remembered playing a fun and simple incremental game called Dwarfs: There and Back Again and it made me want to make an incremental game myself. So I went back and played some other incremental games I enjoyed, such as A Dark Room and Seedship.

While brainstorming ideas on what the game should be about, I thought about why the game jam was created in the first place. Due to rapid climate change, the Earth is being destroyed. Thinking about that, I came up with an idea to model the game after climate change.

A game where you start off happily mining resources without really knowing what you're doing. Where you slowly come to realize that your actions have consequences and you are actively harming yourself. Where you can try to keep up with the high demand you have created but ultimately end up destroying yourself.

Until, that is, you realize that you should slow your pace, try to only consume what you need, and eventually switch over to an alternative source of power. Only then can you win.

If you've played the game, you should be able to see exactly how the game follows this model. You may not have realized it at the time, but you are very much playing a political commentary on climate change. Yep, I said it. I made a political game.

After coming up with this idea, I instantly liked how it would play out. The next step was designing it.

Designing an Incremental Survivor

For the feel of the game, I knew I wanted something that was a bit intense. Some threat that was looming over you, always forcing you to try to be a few steps ahead of it. You know, like climate change.

One thing I knew would be important was a quick feedback loop. The concept of the game was to fail your first few attempts. This meant I would need the game to be played in about 5 minute intervals. Otherwise if it took too long to fail, players would become discouraged at the time they lost and not want to keep playing.

Thinking on all of this, I thought about the game Seedship. I greatly admire the game for not only its great story telling, but also how the games mechanic is always pushing you forward. It also only takes a few minutes to play.

In the game, you need to find a planet rich in a variety of resources, but after each planet you visit you have a chance of damaging your ship. So the game becomes a balancing act of deciding which systems to damage in order to find a better planet. And in the end, your score is a direct result of what systems you were able to save.

So I decided to design my game heavily inspired by Seedship. I wanted to have a ship with different systems that could be damaged, a bit of story telling, and have the player balance efficiency vs. sustainability.

I started jotting down a few pages of notes on how to handle resources and how different systems could interact with one another. After I had refined the ideas down substantially, I started building prototypes to test them. This let me quickly iterate on the ideas until the feel of the game was were I wanted it.

One of the concepts that I had to keep iterating on was the resource systems. I had initially designed it like most incremental games and let you collect an infinite amount of resources. However this hindered the feel of the game as you could just sit and mine forever. So I decided to change it and made the resources very limited.

This lead me to the idea of presenting the status of each system as a bar instead of a number. However, this was hard to balance for as it meant all systems combined couldn't put more than ten load on any one system.

I ended up creating a spreadsheet of all the systems to calculate how much power per second I would need to generate to offset the max load. I also listed the optimal path I thought the game should go and make sure it didn't require too much of any resource at a time, trying to stay around a net 0.

The last design step I did was to figure out a tech tree. I tried drawing the tech tree ideas on paper, but it was a bit tedious having to everything just to move boxes around. I found a free online flow chart tool called draw.io which I used to draw out my planned tech tree.

Programming the Game

While prototyping, I quickly realized that trying to hard code every interaction and UI change would become a nightmare to work with. I decided to create my own one-way data-binding. That way I could maintain all the information in a single state object and any time one of the properties changed, it would handle updating the UI accordingly.

The code for a one-way data-binding involved looking at every elements text content and attributes for the data-binding syntax (in my case, I used double brackets {{}}). The value of the data-binding was a dot-separated path to the property to bind to. The code would then register a callback that would be called any time the path was changed.

For example, if I wanted to bind to the value at systems.power.status, I would write

<div>{{systems.power.status}}</div>

At first it started as a simple property binding. But as the game progressed I added negation and the ability to call functions to transform the data I also added the ability to have the binding only fire once. That way I could populate some initial data but not have it update later.

I also discovered that when binding to HTML input values of number types (number, range, etc.), the browser would throw a warning about non-numeric content in the value attribute. So I created a data attribute data-bind to say which attribute to bind to.

<input type="range" data-bind-value="{{options.volume}}" />

Lastly, since I programmed the game with screen reader support in mind, I had to handle different properties when setting attributes. For example, a falsey value would remove the attribute, unless the value was 0 or if the attribute started with aria and the value was a boolean.

The final binding code is as follows (where event.on is the callback registration).

function setText(el, value) {
  el.innerHTML = value;
}

function setAttribute(el, name, value) {
  // set 0 as a valid attribute
  if (typeof value === 'number') {
    el.setAttribute(name, value);
  }
  // add truthy values or always set boolean aria options
  else if (value || (name.startsWith('aria') && typeof value === 'boolean')) {
    el.setAttribute(name, value);
  }
  // remove falsy values
  else {
    el.removeAttribute(name);
  }
}

// setup bindings. A binding is any string that starts and ends with {{}}, and 
// the content is a dot-separated path. it can also start with ! (negation) 
// and call a transform function using :functionName
// e.g. {{path.to.prop}} {{!path.to.prop}}, {{path.to.prop:transformFunction}}
const bindingRegex = /^\{\{\s?(!?)([\w.]+):?([\w]+)?\s?\}\}$/;
document.querySelectorAll('*').forEach(el => {

// text binding
if (bindingRegex.test(el.textContent)) {
  const match = el.textContent.match(bindingRegex);
  const negation = match[1];
  const path = match[2];
  const transform = match[3];

  const bindOnce = el.hasAttribute('data-bind-once');
  if (!bindOnce) {
    event.on(`${path}-changed`, newValue => {
      newValue = transform ? window[transform](newValue) : newValue;
      setText(el, negation ? !newValue : newValue);
    });
  }

  let currState = state.get(path);
  currState = transform ? window[transform](currState) : currState;
  setText(el, negation ? !currState : currState);
}

// attribute binding
Array.from(el.attributes)
  // no longer make it a live list
  .map(attr => ({ name: attr.name, value: attr.value }))
  .forEach(({ name, value }) => {
    if (bindingRegex.test(value)) {
      const match = value.match(bindingRegex);
      const negation = match[1];
      const path = match[2];

      // value attribute on some inputs (number, range, etc.) will throw a
      // warning about not being a valid number when set to a binding
      // string, so we'll create a binding pointer
      if (name.startsWith('data-bind')) {
        el.removeAttribute(name);
        name = name.split('-').pop();
      }

      event.on(`${path}-changed`, newValue => {
        setAttribute(el, name, negation ? !newValue : newValue);
      });

      const currState = state.get(path);
      setAttribute(el, name, negation ? !currState : currState);
    }
  });

The state code then fires all callbacks whenever a property is changed:

set(path, value) {
  const parts = path.split('.');
  let currPath = this._state;

  for (let i = 0; i < parts.length - 1; i++) {
    currPath = currPath[ parts[i] ] || {};
  }

  currPath[ parts[parts.length - 1]  ] = value;
  event.emit(`${path}-changed`, value);
}

With that, I could write most of the code in just HTML, with a few JavaScipt helpers to handle what should happen when buttons are clicked.

The tedious part of development was managing the large state object for the game. A lot of properties had to be duplicated among the different systems and actions. Adding, removing, or updating anything required editing it in multiple locations. In the end, the state object grew to be about 400 lines long!

It also didn't help that I was prototyping as I designed so I ended up refactoring the state object quite a few times.

In just one week, I was able to to get most of the basic interactions working and was able to focus on adding the tech tree and balancing for the second week. All while making sure I took lots of breaks to avoid burnout (I've burned out a few times on prior game jams).

Making the Interface More Understandable

When I first made the interface for Ravaged Space, it was written as two tables to help facilitate screen readers. I put each piece of information into it's own column, which ended up driving a lot of how the interface looked.

With only two weeks to design and develop the game, I didn't really have any time to playtest it. Which was unfortunate because, as I found out later, the UI was really confusing.

Due to the two table design, all the information was spread out too much. Players were so focused on the buttons in the right table they they didn't notice that the systems were being affected when they clicked the buttons.

Players also didn't understand that the buttons had a cost associated with them as that information was in two other columns. They also had trouble understanding system load and how it affected the game.

Lastly, players were often confused with the modification popups and didn't know what they were choosing between.

All in all, the UI was a mess.

While talking about this with other developers and designers at a local Indie Game Meetup, we came up with the idea to condense the UI as much as possible.

The action buttons moved next to the status so players could easily see what changed when they pressed them. Their cost was also added to the button so all the information was in a single place.

To help with system load, I added a cool pulsing effect to the status bar which shows how much of the resource you would lose on a load cycle. I also made it start slow and then get faster as the load cycle came closer.

I also made sure to add what exactly was changing to each modification popup button so it was clear what you were choosing between.

Playtesting has shown that the updated design is much easier to understand. It's still not perfect though.

I've noticed that players can easily miss when new systems add load, which causes them to lose but not understand why. Hopefully I can address this in the next update by trying to call attention to any changes in system load.

Conclusion

I am very pleased of how the game turned out. I don't often have a game where it goes exactly how I had planned it. It's also fun having the game give the exact feeling I wanted it to give. Others have felt this too and have reached out to say how much they've loved the game as well.

A few weeks ago we merged the largest and most significant performance improvement to axe-core, a culmination of over 6 months of work, and were finally able to resolve the slowest rule we had: color-contrast.

I wanted to take some time to talk about the work that went into improving the performance of the rule. But before I can talk about how we solved the problem, you need to understand how calculating color-contrast works, and why that caused it to be slow.

How to Calculate Color-Contrast

Calculating the contrast between the foreground and background colors of a element isn't a straight forward problem. Getting the foreground color is relatively easy as you can just look at the elements color CSS property. Getting the background color of an element is a bit more involved.

To get the background color you need to know the elements visual DOM stack, which is all elements that visually overlap the element sorted by their visual order.

Without CSS involved, this is just the element and all of its ancestors. But positioned elements, negative margins, and transforms can add or remove elements from the stack. For example, an absolutely positioned element can be anywhere on the page and not just visually above its parent element.

Once you have all the elements of the stack, you can look for the closest one that defines a background color, or use the browsers default if none is defined.

Luckily we don't have to calculate the visual stack ourselves as the browser provides a very handy API called document.elementsFromPoint which returns the visual DOM stack. This is what axe-core uses to get the element stack and run our calculations on.

Why Color-Contrast Was Slow

To figure out why the rule was so slow, I ran a performance audit on the code. Using a performance analyzer, I was able to use the resulting flame graph to see where the most time was being spent in the code. What it showed me was that two browser APIs were taking the most time: elementsFromPoint and scrollIntoView.

Now the reason we were calling scrollIntoView is because the coordinates passed to elementsFromPoint must be within the current viewport (otherwise an empty stack is returned). This means that for every element that is offscreen, we have to scroll the element into view first so we can then call elementsFromPoint on its coordinates.

From the flame graph we can see that those two APIs themselves aren't taking the most time (they aren't the last thing in the column), but that each of the APIs cause the browser to rerender. Rerendering a large page is not quick, and having to do it twice for every element on the page was causing the huge bottleneck in our code.

How We Fixed It

Now that I understood why the color-contrast rule was slow, I needed to figure out if there was a faster way to calculate the element stack that didn't rely on scrolling the element into view and calling elementsFromPoint. This wasn't an easy problem as I had to come up with a more performant solution for a browser API, one that didn't trigger rerendering.

While thinking about this problem, I remembered the old Firefox 3D DOM Visualizer, which essentially showed the element stack. Looking at it reminded me of some of the simple HTML games I've created where the sprites are just rectangles.

This gave me the idea to treat each element as a sprite and perform collision detection on them to determine if they collide (or stack) with one another. Any elements that collided would be part of the same visually stack.

However, running collision detection on every element against every other element would be a very slow operation, possibly even slower than our current code. Thankfully I already knew how to solve collision detection performance problems through a technique called spatial partitioning.

Spatial partitioning is a technique where you divide a space into equal parts and assign each element into one of the parts. Then when you want to run a check, you only need to look at the elements that share the same space. This can help improve performance since you are running the collision check against significantly fewer elements.

Using a Quadtree

I first attempted to use a quadtree to group all the elements on the page. In a quadtree you divide the space into 4 equal parts (hence the name quad). Each of these parts can be further subdivided into 4 equal parts if they contain more elements than a predefined threshold. Spaces can keep subdividing until a max depth is reached or there are no more elements to add.

Unfortunately, through lots of testing I found that a quadtree took far too long to populate to make it a viable solution on large pages. With 50k+ elements on a page, the quadtree was continually divided and subdivided. Each time it divided I had to recalculate each elements position and add them to their appropriate subdivision.

In total, it took around 5 seconds to finalize and then another 5 seconds to process all the stacks. Although this was better than freezing the browser, I knew it could be faster.

Using a 2D Grid

I decided to try a simpler approach and create a 2D grid of the page and assign each element to every cell of the grid it belonged to. Then when I needed the stack I would just look at a single grid cell and run a collision check on just those elements.

This proved much faster than the quadtree approach, but I ran into a few problems when elements had scroll regions. Because of the scroll, elements inside scroll regions are not on the same coordinate system as other elements on the page.

For example, an element with a scroll region could visually be only a few hundred pixels tall, but the entire height of the scroll region could be a thousand pixels tall. Only the elements that are inside the current scroll area take up visual space while all of the other elements are essentially hidden. However, elements outside the scroll area could still contribute to the background color of it.

To handle this, I decided to treat each scroll region as its own separate grid. When I encountered an element with a scroll region, I would add the element to the grid as normal. Then I would create a subgrid for that element and add all of its descendants to just the subgrid.

When I wanted to find all elements that belong to the same stack, I would first look at the current elements grid and find all elements that collided with it. Then if the element had a parent grid, I would look the parent grid and find all elements that collided with the parent scroll region, and so forth and so on.

Doing this allowed me to treat each scroll region as it's own collision space and accurately determine the elements visually stack.

Visually Sorting the Stack

Now that the page was visually grouped, I had to finish the process by visually sorting all the elements in the stack.

Sorting elements visually is a lot harder than grouping them by their position. I had to understand exactly how a browser renders a page in order to mimic that rendering though JavaScript. This meant understanding stacking contexts and how CSS properties could affect the visual position of elements.

Without CSS involved, visual sorting is mostly just calculating the position of the element in the DOM compared to another element. Any element that comes after another is higher in the visual order. For this, I used the browser API Node.compareDocumentPosition to know which elements came after another.

With CSS involved, I also had to manually calculate stacking contexts and CSS position layouts to determine the visual order. Thankfully MDN has great docs on how browsers visually sort elements so I was able to use them as a base reference while writing the code.

One fun problem I ran into was handling positioning of Shadow DOM elements. I discovered that when using compareDocumentPosition on elements in two different DOM trees, it does not correctly return the elements position. Instead, the element in the Shadow DOM would always return as coming after any other element, including the HTML element.

To handle this, I had to walk up each of the DOM trees of the elements until I found a DOM tree they both shared. Then I could compare the position of the respective parent elements in the shared tree to know which element came after the other in the different trees.

<div>
  <div>
    #shadow-dom
      <span id="A">Element A</span>
  </div>
  <span id="B">Element B</span>
</div>

In the above example, #A and #B are in two different DOM trees (as #A is in a Shadow DOM). #A's parent element shares the same DOM tree as #B, so we can compare these two elements to each other. This allows us to know that #B comes after #A.

Visually sorting the stack took the most time to write and test as I had to do a ton of regression testing every time I made a change. Usually this involved running elementsFromPoint on a lot of pages and then comparing the results to what my code produced.

Doing this did find an interesting discrepancy between how Firefox and Chrome calculate elementsFromPoint though.

From the best that I can tell, there is a very interesting edge case in how the browsers treat floating point numbers when determining which elements belong to a stack. In Chrome they seem to round up the number while in Firefox they keep the number as is. This can cause the browsers to return different results (an element belonging to the stack in Chrome is missing in Firefox).

For our code, I decided not to round the number, mimicking Firefoxs approach.

Memory Use

Now we can't talk about improving speed without also talking about memory consumption. Improving speed usually comes at the cost of increased memory as you are caching information to improve speed.

So how much memory does saving every element into the 2D grid (and respective subgrids) take? I took three heap snapshots of a large site (10k+ nodes) to find out.

The first was when the page was loaded and the axe script was on the page but not run. This gave me a baseline to see how much memory the page used by itself.

The next was after running axe but without creating the 2D grid. The last one was after axe had created the 2D grid.

Now typically axe cleans itself up after a run so there won't be an increase of memory use after it finishes. To compensate for this I made sure to save off axes internal data during the run so I could look at it after the run completed.

From the snapshots we can see that the page itself has a baseline memory use of 17.6 MB (with axe on the page). After running axe but without creating the 2D grid it uses 23.1 MB, an increase of 5.5 MB. Axe with the 2D grid causes the page to use 29.9 MB, an increase of 6.8 MB from axes normal memory use.

This means that creating the 2D grid and saving all elements to their respective cells doubles the memory use of axe from 5.5 MB to 12.3 MB.

Is this a problem? We didn't think so. Doubling our memory footprint on very large sites in exchange for actually being able to run the rule in a decent amount of time is worth the memory trade off. However, it's good to keep that in mind as we move forward so we don't continue to use too much memory.

Final Result

After getting the code to work to my satisfaction, and trying to optimize it to the best I could, I was able to get the rule to complete in 5 seconds on even the largest of pages (50k+ nodes).

From the flame graph you can see that the call to dom.getElementStack takes about one second to complete, and then a lot of very narrow stacks for each element. The getElementStack function is what kicks off creating and populating to the 2D grid. Furthermore, we can see that the code is no longer triggering rerendering anywhere during the run.

If you're interested in trying out the new code, you can download it from NPM using the next tag or use axe-coconut. If you find any problems with the color-contrast results, please file an issue so we can fix it. I expect there to be a few kinks to work out.

A ligature icon is a special type of ligature where instead of a combination of letters it displays an icon. For example, a ligature icon for the word "file" would replace the word with an icon of a file. Examples of a ligature icon fonts include Material Icon, Ligature Symbols, and Symbolset.

The problem with ligature icons is that there is no easy way to detect when a font uses ligatures and what words are associated with ligature icons.

It took me awhile, but I think I found a reliable and accurate way to detect them. If you don't want to read through my process, you can skip to the end where I post the code.

Different Ideas for Detecting Ligature Icons

Through CSS Properties

I initially thought I could detect a ligature font based on the CSS properties used when declaring it. I noticed ligature icon fonts typically use a property called font-feature-settings and thought it might be required to display a ligature icon. However, turning the property off in devtools didn't stop the icon from displaying so it's not a requirement to show them. Even though some ligature icon fonts use it, I couldn't rely on it.

Additionally, just because a font uses ligature icons doesn't mean that it will only be used for icons. Knowing if it's a ligature icon font would not be enough to guarantee all uses of it are icons.

Parsing the Font File

My next idea was seeing if I could parse the font file for information about which words were ligatures. I discovered the website Font Drop which could parse a font file and display all the information about it, including its ligatures. The website said it uses the opentype.js library to parse the font files, which I figured I could also use.

Unfortunately, I soon found out that the library does not support WOFF2 files, which is what Material Icon uses. There's been an open issue to support it, but so far no work has been done on it. In the same issue, users mentioned a fork of the library that supposedly supports WOFF2, but it doesn't seem to be actively developed. This meant that if we ran into issues with the library, we wouldn't be able to get them fixed without making a fork ourselves, which was less than ideal.

Width of the Word

I next thought I could determine when a ligature icon was used by checking the width of the word. I figured if the word "file" was replaced by a single character icon, then there would be a substantial difference in its rendered width compared to its word width (1 character vs. 4 characters). However, I couldn't just ask what the width of the textContent was since it would return the word "file" and not the ligature icon.

Whilst thinking about this, I remembered the canvas API measureText which can measure the width of a string based on a given font size and font family. I didn't know if it could handle ligature icons, but testing it out showed that it could.

I thought I could just add a single whitespace character to the middle of the word so the word would no longer render as an icon, and then compare that width to the width of the unchanged word. This sort of worked until I ran into two problems.

The first problem was that the width of a whitespace character isn't always consistent, but can differ depending on where it's located or what letters surround it. For example, in the font Big Shoulders Text a whitespace character at 36px is measured to be 7.45px wide. However, it's 8.35px wide when between the letters "r" and "e". This meant that adding a whitespace character in the middle of a word could give different widths depending on which characters the whitespace separated.

The second problem occurred when I found a ligature icon that was only two characters long. The font Ligature Symbols has a ligature icon for the word "vk." When I took the width of the word at 36px it measured 30.76px wide, while the width of a whitespace character was 12.94px wide. So together I expected the final width of the word and whitespace to be about 43.7px wide. However, the actual width was 49.99px wide, a difference of about 6px.

Since a whitespace character can differ in width, I couldn't be sure if that 6px difference was due to the word being replaced by a ligature icon or because the whitespace character was longer between the "v" and "k."

I also tried to measure the width of each individual character and add them together to get the final expected width, but this also proved to have too much variance due to letter spacing differences. In another experiment, I tried adding a zero-width-space character to the word but it seems the browser ignores these when determining the ligatures and so it didn't change the width from the word without a zero-width-space.

Compare Image Data

My last idea to try, and the one that ended up working, was to compare the pixel data of the first character to the pixel data of the entire word. The idea was that if I created a canvas the exact size of the first character and drew that character, drawing the entire word on the same size canvas (so the remaining letters wouldn't be visible) should produce the same image of the first character. If the images were different, I would know that the word was replaced by a ligature icon.

Before I started working on this solution, I already knew I was going to have to account for normal ligatures such as ae, fi, and ffi. That meant that small differences in the image should be ignored. It also meant that that the canvas size would need to be large enough to account for some pixels changing due to ligatures, but small enough to be performant when calling getImageData and looping through the data (twice).

As I began thinking about this, it all started to sound like a statistics problem in that I needed a large enough canvas size (sample size) to detect a (statistically) significant change. So I thought why not break out the statistics! After all, my high school teacher would be proud knowing I finally got to use it after all these years.

Note: the goal wasn't to be statistically accurate, but to use statistics to help inform our decision about numbers. That way I wasn't just choosing magic numbers out of a hat but had some reasoning behind them.

Determining Sample Size

In statistics, there's a few ways you can determine sample size depending on what information you already have or can find. For my particular case, I needed to choose a sample size without knowing anything about the data (it's mean, standard deviation, etc.). Luckily, there's a formula for determining sample size based only on how confident you want to be (confidence interval) and how much margin of error to account for.

X = Z**2 ­* p * (1 - p) / MOE**2

Where:

• X = sample size
• Z = z-score (determined from the confidence interval)
• p = sample proportion (the expected results)
• MOE = margin of error

I wanted my results to be super accurate, so chose a very high confidence interval of 99.9% (a z-score of 3.291), and kept the standard margin of error of 5%. For the sample proportion I chose 50% as that gives the largest sample size needed.

Using these numbers, the sample size needed was 1072. Square rooting that gave me a canvas size of about 32px x 32px.

Determining Percent Difference

Now that I knew what canvas size to use, I needed to know what percent change was needed to detect an icon. I wrote a script to find every icon on the Ligature Symbols webpage and calculate the percent difference from the first character to the whole word.

const canvas = document.createElement('canvas');
const context = canvas.getContext('2d');
const fontFamily = 'LigatureSymbols';
const percents = [];

let fontSize = 36;  
let font = `${fontSize}px "${fontFamily}"`;

document.querySelectorAll('.lsf.symbol').forEach(node => {
  const word = node.textContent;
  if (!word) return;  // there was a symbol without text

  context.font = font;
  let width = context.measureText(word.charAt(0)).width

  // ensure the width of the first character is the required size
  // (36 pixels does not mean the font is draw that wide)
  if (width < 33) {
    let ratio = 33 / width;
    width *= ratio;
    fontSize *= ratio;
    font = `${fontSize}px "${fontFamily}"`;
  }

  canvas.width = width;

  // the font size typically defines the height (including 
  // ascenders and descenders) of a font. this usually means we'll 
  // end up with a taller canvas than it is wide
  canvas.height = fontSize;

  // changing the size of the canvas resets all canvas properties, 
  // include font
  context.font = font;
  context.textAlign = 'left';
  context.textBaseline = 'top';

  // draw the first character and get the image data
  context.fillText(word.charAt(0), 0, 0);
  const firstCharData = new Uint32Array(
    context.getImageData(0, 0, width, fontSize).data.buffer
  );

  // draw the whole word and get the image data
  context.clearRect(0, 0, width, fontSize);
  context.fillText(word, 0, 0);
  const wholeWordData = new Uint32Array(
    context.getImageData(0, 0, width, fontSize).data.buffer
  );

  // we only want to know when a pixel has changed so can ignore 
  // the value at the pixel and only look to see if they were both
  // turned on or off
  const difference = firstCharData.reduce((diff, pixel, i) => {
    if (pixel === 0 && wholeWordData[i] === 0) return diff;
    if (pixel !== 0 && wholeWordData[i] !== 0) return diff;
    return ++diff;
  }, 0);

  percent = (difference / firstCharData.length).toFixed(2);
  percents.push(percent);
});

console.log(percents.sort().join(', '));

The resulting data showed that the minimum difference was 17%. Running the same code for Symbolset Geomicons Squared resulted in a minimum difference of 26%. This informed me that all ligature icons could be caught by using a difference threshold of about 15%.

All that was left to do was ensure that a normal text ligature wouldn't be flagged as an icon. I ran the same test on a few Google Fonts that had text ligatures and they showed that the fi ligature is about a 5% difference, which was perfect.

Caveats

Even though this approach works for the 3 sets of ligature icon fonts I tested, I would need to test it against a larger sample size to ensure my results are accurate. Unfortunately I couldn't find very many fonts that use ligature icons.

This approach also does not work for single character ligature icons as there would be nothing to compare the original font to before it changed.

Lastly, in testing Material Icon I found that they don't have any character data for the standard alphabet. This resulted in differences as low as 4% (a blank canvas compared to a single line for "minimize"). I had to adjust the code to check to see if the first character image data was empty and if it was assume the font was a ligature icon font (thus skipping the comparison).

Final Code

Putting it all together, we can determine when a string of text has been replaced with a ligature icon using the following code:

(function() {
  const canvas = document.createElement('canvas');
  const context = canvas.getContext('2d');

  window.isLigatureIcon = function isLigatureIcon(node) {
    const word = node.textContent;
    if (!word) return false;

    let fontSize = 36;
    let fontFamily = window.getComputedStyle(node).getPropertyValue('font-family');
    let font = `${fontSize}px "${fontFamily}"`;

    context.font = font;
    let width = context.measureText(word.charAt(0)).width

    // ensure the width of the first character is the required size
    // (36 pixels does not mean the font is draw that wide)
    if (width < 33) {
      let ratio = 33 / width;
      width *= ratio;
      fontSize *= ratio;
      font = `${fontSize}px "${fontFamily}"`;
    }

    canvas.width = width;

    // the font size typically defines the height (including 
    // ascenders and descenders) of a font. this usually means we'll 
    // end up with a taller canvas than it is wide
    canvas.height = fontSize;

    // changing the size of the canvas resets all canvas properties, 
    // include font
    context.font = font;
    context.textAlign = 'left';
    context.textBaseline = 'top';

    // draw the first character and get the image data
    context.fillText(word.charAt(0), 0, 0);
    const firstCharData = new Uint32Array(
      context.getImageData(0, 0, width, fontSize).data.buffer
    );

    // check to make sure there was data for the first character, 
    // if not it's assumed to be a ligature icon font
    if (!firstCharData.some(pixel => !!pixel)) return true;

    // draw the whole word and get the image data
    context.clearRect(0, 0, width, fontSize);
    context.fillText(word, 0, 0);
    const wholeWordData = new Uint32Array(
      context.getImageData(0, 0, width, fontSize).data.buffer
    );

    // we only want to know when a pixel has changed so can ignore 
    // the value at the pixel and only look to see if they were both
    // turned on or off
    const difference = firstCharData.reduce((diff, pixel, i) => {
      if (pixel === 0 && wholeWordData[i] === 0) return diff;
      if (pixel !== 0 && wholeWordData[i] !== 0) return diff;
      return ++diff;
    }, 0);

    return (difference / firstCharData.length).toFixed(2) > 0.15;
  };
})();

<!-- Cell.vue -->
<script>
export default {
  functional: true,
  props: ['cellData'],
  render: function (h, context) {
    return [
      h('td', context.props.cellData.category),
      h('td', context.props.cellData.description)
    ]
  }
}
</script>

The first tricky part was that I discovered that you can't use propsData to pass props to a functional component. Instead you need to pass a context object that has a props property.

Next I tried to shallowMount the component as I typically do, but that resulted in a warning:

[Vue warn]: Multiple root nodes returned from render function. Render function should return a single root node.

// Cell.spec.js
import { shallowMount } from '@vue/test-utils'
import Cell from '@/components/Cell'

wrapper = shallowMount(Cell, {
  context: {
    props: {
      cellData {
        category: 'foo',
        description: 'bar'
      }
    }
  }
}); // [Vue warn]: Multiple root nodes returned from render function. Render function should return a single root node.

I next tried wrapping the component in a single <div> to create a single root node. That didn't work either though as I got an error:

[vue-test-utils]: mount.context can only be used when mounting a functional component.

// Cell.spec.js
import { shallowMount } from '@vue/test-utils'
import Cell from '@/components/Cell'

wrapper = shallowMount('<div><Cell></div>', {
  context: {
    props: {
      cellData {
        category: 'foo',
        description: 'bar'
      }
    }
  }
}); // [vue-test-utils]: mount.context can only be used when mounting a functional component.

At this point I didn't know what to do so (as passing propsData didn't work either), so I turned to StackOverflow and asked there.

It turns out that you need to create a wrapper component that renders the functional component and forwards it all props and listeners. Then you can mount the wrapper component to be able to test the functional component.

// Cell.spec.js
import { mount } from '@vue/test-utils'
import Cell from '@/components/Cell'

const WrappedCell = {
  components: { Cell },
  template: `
    <div>
      <Cell v-bind="$attrs" v-on="$listeners" />
    </div>
  `
}

const wrapper = mount(WrappedCell, {
  propsData: {
    cellData: {
      category: 'foo',
      description: 'bar'
    }
  }
});

describe('Cell.vue', () => {
  it('should output two tds with category and description', () => {
    expect(wrapper.findAll('td')).toHaveLength(2);
    expect(wrapper.findAll('td').at(0).text()).toBe('foo');
    expect(wrapper.findAll('td').at(1).text()).toBe('bar');
  });
});

The last piece of the puzzle was figuring out how to test that a parent component that used the functional component passed it the correct props. Normally you would use wrapper.props() to test the props, but this doesn't work for a functional component as you get an error:

[vue-test-utils]: wrapper.props() cannot be called on a mounted functional component.

Instead, what I figured out you can do is use a similar method as testing the functional component. When mounting a component, you can pass it a stubs option in which you can stub one component out for another. This allows us to create a wrapper component and stub it for the functional component.

Since the wrapper component isn't functional, you can call props() on it to test that we're passing it the correct data. The wrapper component doesn't need to render the functional component or even register it as a component. The only requirement is that it declares the same props as the functional component.

// ParentCell.spec.js
import { shallowMount } from '@vue/test-utils'
import ParentCell from '@/components/ParentCell'

const Cell = {
  props: ['cellData'],
  template: '<div></div>'
}

describe('ParentCell.vue', () => {

  let wrapper;
  beforeEach(() => {
    wrapper = shallowMount(ParentCell, {
      stubs: {
        Cell: Cell
      }
    });
  });

  it('should correctly render the cell', () => {
    expect(wrapper.find(Cell).exists()).toBe(true);
    expect(wrapper.find(Cell).props('cellData')).toEqual({
      category: 'foo',
      description: 'bar'
    });
  });
});

However, these examples showed it working in a way that I could never get working.

The basic setup that each of the examples gave was to create a Tiled map and add a layer called Ground which contains ground tiles in the shape you wanted.

Next, you create another Tiled map (I called it wall-rules.tmx) in the same directory and create three layers: regions, input_Ground, and output_Walls. Using these layers, you create a rule to add a single wall above a single ground tile.

AutoMap Rule Layers

Tile layer	Name
	regions
	input_Ground
	output_Walls

Lastly you create a rules.txt file in the same directory as the Tiled map that lists each rule map you want to include.

wall-rules.tmx

With that, every example showed you should be able to run the AutoMap feature and it would populate the walls above the top row of ground tiles. This is the part that never worked.

It turns out that at the end of 2017 a new feature was added that prevents these examples from working as is. The new feature added a flag to input layers called StrictEmpty that changed the default behavior to not match empty tiles:

In "StrictEmpty" mode, empty tiles in the input region match empty tiles in the set layer. So when an "input" layer contains an empty tile within the input region, this means an empty tile is allowed at that location. And when an "inputnot" layer contains an empty tile within the input region, it means an empty tile is not allowed at that location.

Without the "StrictEmpty" option, when no "input" layer specifies any tile for a given location, and no "inputnot" layers exist, any tile that isn't used elsewhere on any input layer is considered valid. Also, when an "inputnot" layer contains an empty tile, it is simply ignored. This behavior can be convenient, but it is not always desired.

The "StrictEmpty" mode can be enabled per input layer by adding a custom boolean property named "StrictEmpty" with the value "true".

So to get the examples to work, what you have to do is add a Layer Property to the input_Ground layer called StrictEmpty of type Bool and set the value to true.

Once you do that, the AutoMap feature will now work.

You can download the complete example files from github so you can try it out yourself.

For example, all data in LocalStorage is saved as a string. This means saving the boolean true will be saved as the string "true". A common pattern for reading from LocalStorage is to use JSON.parse() to parse the data on read. Since the parse could fail for non-JSON like data, we wrap the parse in a try/catch and fallback to the raw text value.

let value = localStorage.getItem(key);
try {
  value = JSON.parse(value);
}
catch(e) {}

This pattern can also be helpful for when you need to make an HTTP request for data that could be JSON or text. But when trying to do this pattern using fetch(), I ran into some problems.

Typically when you read JSON from a fetch call, you use response.json() to return a promise which resolves with the parsed JSON.

fetch('/file.json')
  .then(response => response.json())
  .then(data => {
    // data is now parsed JSON
  });

I figured that if the response.json() promise failed, I could try to parse the response as text using response.text(). However, doing so resulted in a TypeError: body stream already read error.

fetch('/file')
  .then(response => 
    response.json().catch(() => response.text())
    // TypeError: body stream already read
  )

It turns out you can only read the response body once. Not knowing what to do, I turned to the internet. Thankfully, Jake Archibald wrote an article where he mentioned cloning the stream to be able to read it twice.

By using response.clone() we can create a copy of the response to parse as JSON, and if that fails we parse the original response as text.

fetch('/file')
  .then(response => 
    response.clone().json().catch(() => response.text())
  ).then(data => {
    // data is now parsed JSON or raw text
  });

After scouring the internet, I was finally able to find a satisfactory explanation from the Microsoft UWP design docs.

• Use a toggle switch for binary settings when changes become effective immediately after the user changes them.
• Use a checkbox when the user has to perform extra steps for changes to be effective. For example, if the user must click a "submit" or "next" button to apply changes, use a check box.

In other words, use a button for changes that should happen immediately and a checkbox for changes that should take place after the user submits them.

When I thought about it this way, these guidelines reminded me of the guidelines for when to use a button vs when to use a link.

Use a button to trigger interactions on the page and a link to navigate or retrieve information.

In both cases, a button is used to trigger an action.

To be sure my new findings would be inclusive, I asked the experts on the A11y Slack channel. They confirmed that a checkbox would typically be used inside a form (where the user would submit it) and a button would perform an action.

Going back to the notify by email toggle control example, it can be written as either a checkbox or a button. Depending on the context in which it is used will determine how it should be coded.