Getting into the Spirit of Shortcuts

December 29, 2021

The Background

Like many families, deprived of much to do outside our home in the early days of the pandemic, my fiancée and I found comfort and entertainment in board games. Although the level to which we’ve chosen to self-isolate has fluctuated, board games have remained a big part of our routine.

In no particular order, here are a few that have gotten the most play time:

That last entry on the list, Spirit Island, is especially notable for being the most strategically complex and logistically complicated game we’ve ever played. It also commonly takes us a long time (at least two hours) to finish. While it really sucks to lose a game you’ve sunk that much time into, winning can be quite satisfying—so much so that we enjoy keeping score.

The Problem

A brief section towards the end of the instruction manual provides a suggested process for calculating your score. The exact algorithm differs depending on whether you’ve won or lost, but in general, the score factors in the difficulty rating of your chosen setup, how quickly you reached the game’s outcome, and (by counting up various pieces on the board) how decisive that outcome was.

The process isn’t really that complicated, but what makes it slightly annoying is the need to look up the difficulty on a provided grid. (The exact number depends on which “adversary” you decided to play against, the chosen level—or intensity—of that adversary, and a few other factors.) You also, of course, have to do a bunch of math.

Because we’re nerds, we like to record the game setup and resulting score in a chart so we can see our progress over time and compare how we did. When you put this all together, it’s a lot of shuffling among instruction pages, the board itself, a calculator app, and the note-taking app where we keep the scores.

While it’s not a huge deal, this could still be a lot easier if the score could be calculated automatically, kind of like how it might be done for you in a video game.

The Objective

What we needed was some kind of app that would allow us to input the details about the game setup and outcome. Then, the app could handle all the work of looking up the difficulty and calculating a score. Bonus points if it could provide the answer in a way that made it easy to paste into our record-keeping system.

The Solution

Creating an actual phone app would probably be more effort than it’s worth. My iOS programming skills are pretty thin, and while I’ve gotten some practice recently, Apple also doesn’t make it easy to keep a custom app on your phone for an extended period of time without paying for a $99 annual membership in their developer program. (Without a membership, you need to reinstall your app once a week to keep it functional.)

A web app would be a cheaper (i.e. free) option that could better align with my skill set, but I had a different idea in mind. Since the ultimate goal was to be able to paste the result into a note in Apple’s notes app, what if I could calculate the score without ever leaving the notes app?

The only way to really make that work would be to use Apple’s Shortcuts app.

The purpose of the Shortcuts app is to create routines (what, in the old days, might be referred to as “scripts” or “macros”) that link actions from various apps together to accomplish some common or repetitive task more quickly or conveniently than if you had to do it all manually. These shortcuts can be turned into Home Screen icons, accessed via the iOS share sheet, or called upon via the Siri voice control interface.

Significantly, a shortcut can also be accessed via the iOS widget panel, which means you can call upon a particular routine with just a couple swipes (one down from the top of the screen, and then one from left to right) followed by a tap. And, depending on how the shortcut is designed, this means you may not even have to leave the app you’re currently using. Bingo!

The Outcome

As alluded to above, the shortcut I created does not require leaving the app you’re currently using. That’s because, despite the whole point of Shortcuts being to get apps to talk to one another, this particular routine does not actually involve talking to any apps.

Instead, it just asks you a series of questions, some multiple choice and some requiring you to input a number. Then, for all intents and purposes, it uses those answers to plop some numbers into a formula and calculate a solution. As the final step, it ask the user whether the answer should be copied to the clipboard. If so, that answer can then be pasted wherever it’s needed (e.g. into our Spirit Island record-keeping note.)

In actuality, it’s a little more complicated than that for a couple reasons. The first is that the way the Shortcuts app works (which involves dragging and dropping a bunch of building blocks rather than writing code) requires that you break long mathematical formulas into multiple steps, not unlike how you might actually solve a problem on paper if you were asked to “show your work.”

The second complication is that you need a way for the shortcut to be able to look up the difficulty ratings based on your answers to the questions. Essentially, I had to create a machine-readable version of the grid from the instruction manual. Luckily, the Shortcuts app can handle a type of data structure known as a dictionary, which is also sometimes referred to as an “associative array” in computer programming.

A dictionary or associative array is a collection of key-value pairs. The idea is that if you give the program a particular key, it can look it up in the dictionary/array and return the associated value.

You can see a portion of the Difficulty Dictionary that I constructed below.

The main dictionary consists of a series of keys corresponding to all the adversaries you can play against. And each of those keys is associated with another dictionary whose keys represent the different intensity levels possible for each adversary. And finally, each of those keys are associated with yet another dictionary consisting of a single key, “difficulty,” which is associated with a single value corresponding to the difficulty rating.

The structure is a little convoluted to explain, but it’s consistent and predictable, which makes it easy for the shortcut to drill down step-by-step to the desired rating.

There’s one other (less complicated) dictionary involved to account for an additional scorekeeping quirk. The rest is fairly straightforward (yes-no questions, if-then logic, etc.).

The Takeaway

Want to check out what the finished product looks like? Or maybe you actually play Spirit Island yourself and would love to actually use this tool?

If you have an iPhone or iPad (or a computer running macOS 12 “Monterey”), click this link to add it to your device.

(Note: This shortcut only accounts for the base game. It does not include any adversaries or other elements from any of the expansion or promotional packs that have been released for Spirit Island.)

Thanks for following along. Feel free to recommend cool board games that are great for just two players in the comments!