#1: Catacombs, Spatial Audio, and Animated Album Artwork

Prototyping a new dice mechanic for an adventure game and talking about Spatial Audio / animated artwork on Apple Music.

Nov 30, 2022

Dear Reader,

Welcome to the first proper issue of The Dodo Developer, a newsletter where I’ll hopefully be able to give you some insight around independent app development. I’m expecting that the first few issues will be quite long as I have plenty of apps to go through; I also expect that the format will change quite a bit based on your feedback. You can leave any comments on this issue or you can contact me directly via ben@bendodson.com - I’m always grateful for your critical feedback.

In this first issue I’m going to be giving you early access to a game mechanic I’ve been working on, give you an update on where I am with Spatial Audio matching, and demonstrate how I was able to get animated album artwork downloads working (and how I fixed them when they broke). I’ll also be putting a roadmap at the end showing what I plan to work on over the next two weeks as one of the main reasons for doing this was to keep me motivated on my own projects.

When I launched this newsletter last week I had a rough number of subscribers I hoped to achieve before the end of the year; I’m very happy (and slightly nervous!) to say that more than 3x that number are already reading these words. Thank you for being one of them. I hope you’ll find something interesting in today’s issue.

— Ben

Catacombs

I’m a big fan of the interactive novels made popular by the Fighting Fantasy and Choose Your Own Adventure books of the ‘80s and ‘90s. Over the years I’ve toyed with the idea of making my own digital versions; this interest has only grown with my discovery of Ink, a narrative scripting language that powers all of Inkle’s games such as 80 Days and Heaven’s Vault.

Whilst I’m comfortable with Ink and how to create an adventure, the one thing that has always tripped me up is how to do something a bit different with regards to fighting. In a traditional Fighting Fantasy book you typically roll 2d6 plus your skill modifier and compare it to 2d6 plus your opponents skill modifier with the loser taking 2 points of damage. This works well enough but I’ve never been keen on it mechanically and I wanted to do something else for my own adventures.

This year, two key games – Citizen Sleeper and Marvel Snap – made me think of something that could potentially work so last week I decided to throw a prototype together in a few hours as if I were participating in a game jam. The result is Catacombs:

Download Catacombs

In Catacombs you will fight a number of foes as you delve into the sprawling undercity of Buden1. With each encounter you'll see three lanes in front of you similar to the four-card lanes in Marvel Snap. The difference here is that each lane can have up to two dice placed in them. In the first battle you'll only have three dice but by the final boss encounter you'll have six dice available to you as well as a special ability that can be activated with a star faced die. Your enemies also get stronger with several having their own special abilities such as the zombie above being able to convert any of your sixes to a one.

Once all the dice are placed, the values in each lane are totalled and the loser in each takes a point of damage (a draw in a lane counts as a miss with nobody being injured). Some text will be displayed to show what happened in the fight and then you’ll repeat the process until one of you is dead. I’m not a fan of showing specific hit points to players so instead the text is crafted to give you a general inclination as to the current state of yourself and your opponent such as a DM might give in game of Dungeons & Dragons. For example, “The bandit is looking very pale. They are surely not long for this world."

The battle prototype was created in around 3 hours using SwiftUI. It was incredibly quick to mock up as I was able to use the SF Symbols icon set that Apple provides for all of the game assets such as die, score counters, and even the dotted square outlines. I used the SwiftUI Drag-and-Drop package from Joel Huber to get the most challenging part (actually moving the dice around) done in about 20 minutes.

I cannot overstate how good a feeling it is to be able to imagine something and then have it running on a physical device in under half a day. Whilst you can prototype on paper, I find doing it this way far more rewarding as you can feel it working and make rapid changes; for example, initially it was just one dice per lane but it felt too boring as you were always just waiting to see what numbers you got vs the opponent as you’d always fill both sides. With two die slots per lane, there is some tactical decision to be made as you don’t have enough dice to fill every slot; instead you might choose to spread across each lane or pile everything into two slots knowing you’ll likely take at least one point of damage. On paper I may not have come to that realisation and spent time working on other things before the core mechanic was locked down; doing it as a working prototype meant I got to play it and then fix it almost immediately.

I wasn’t planning on doing anything other than a single fight to demonstrate the mechanic but as I was able to get it working so quickly I was able to branch out to six increasingly difficult fights that unlock as you win each battle. I spent around 4 hours adding ~200 lines of text for the damage descriptions and added some graphical elements from an asset pack I’d previously purchased2. I wanted to add some story before each of the fights but the time taken for the damage text drained me of the desire to do any more writing and I knew if I started down that path I'd want to use Ink and start adding choices, etc.

One thing I’ve neglected to mention is that this doesn’t just have to be used for fights but could also pair well with skill checks such as attempting to pick a lock or persuading a bouncer to let you into a VIP lounge. I think there are definitely ways the mechanic could be extended such as retaining any dice you don’t use for the next round (as if you are winding up for a big hit) and doing more with the special abilities beyond die value manipulation.

For around 8 hours of work I’m very pleased with the outcome and definitely think I’ll be using this idea in my upcoming narrative adventure game, The Dumbwaiter3.

You can try out Catacombs right now with this exclusive TestFlight Link:

Download Catacombs

* Catacombs will run on any iOS device running iOS 16 or greater. It’ll also work on any Mac running on Apple Silicon. Apologies, this is just an iPhone test so the design is not optimised for iPad or Mac.

If you give it a try I’d love to hear what you think about the dice mechanic, especially if you have suggestions for improvements. Also, do you think it’s worth wrapping this prototype up in a story and releasing it as a small game?

Related Links

Getting Started with SwiftUI in 30 Minutes or Less - I dismissed SwiftUI back in 2021 after falling foul of its many, many, idiosyncrasies but this article by Richard Turton made me want to try again. I’m glad I did! I still don’t think it’s production ready but it worked great for this prototype.
The story of Games Workshop and Fighting Fantasy - An excellent episode of the One-to-One podcast which dragged me back to the Fighting Fantasy books (including the two new ones released this year).
Marvel Snap designer Kent-Erik Hagman talks smart card game design - It’s always good to hear how game mechanics are created (and what was left on the cutting room floor).

Spatial Audio Matching

I’m a big fan of Spatial Audio, but Apple’s implementation within the Apple Music client leaves a lot to be desired. For example, there is no way to see which of your songs have been upgraded to Spatial Audio. This is mostly because the client doesn’t know! It only checks when you start playing a song which is why you sometimes get a weird jump from stereo to Spatial Audio a few seconds into a track.

At WWDC 2022, Apple introduced v1.2 of the Apple Music API, a web service that allows you to lookup track information. The thing that caught my eye was the addition of a new audioVariants property that included such things as lossless and dolby-atmos4. With this I was able to build a rudimentary scraper that could take a list of Apple Music identifiers from my music library and then search the albums to find which tracks had been updated.

Once that worked, I set it to check through my albums once a week to look for changes and then augmented that with Apple’s own Spatial Audio playlists. As of now, there are 958,550 tracks in my database5 of which 54,739 are tagged with the dolby-atmos variant. The next step is to add your music to the database.

The way I’m planning to do this is to update my Music Library Tracker app. This is an app that already has a complete list of all of your songs within it so the steps to enable matching are relatively straightforward:

Update the app so that it gets all of your song ids together and send them to my server where they will be automatically added into the database and checked for Spatial Audio.
Let the server respond to this list of ids with a similar list detailing which songs have the dolby-atmos variant.
Automatically generate a playlist of these tracks on your device.

With this in place, the dream scenario is that you can open the app, press a button, and within a few seconds have a new playlist generated for you which contains all of your Spatial Audio tracks. There are, however, a few difficulties which is why this isn’t already running.

Not all of your songs in Apple Music have ids I can use to match against my database. This is especially true if you have a lot of purchased music or tracks created via iTunes Match. It seems to be that the MPMediaLibrary framework on iOS only has identifiers for songs that have been added from the Apple Music service (likely not an issue for newer users but potentially a problem for users with historic libraries). The solution to this is to use string matching (i.e. comparing name, artist, and album against the dataset) but then I could be sending a lot of data for large libraries. This is likely something for a later version once the foolproof matching is working.
Depending on your country, your songs may not match my database. At the moment I search for tracks against the UK storefront and then the US one if that fails (as my library is using a UK Apple Music account). I suspect I’ll need to attempt to match against the US dataset as that will be the largest and then potentially store duplicate information for other countries which will slow down searches, etc. It may be that the first version just supports UK, US, and Canadian accounts.
The UI for something like this is fairly difficult as I don’t want to just have a huge splurge of tracks in a random order but there does need to be some way to browse the tracks that have been updated. Ideally it also needs to be able to tell you what changed since the last time you checked...
The final issue is when to do the checking. As Music Library Tracker is a one time purchase it isn’t feasible to allow for checking to happen in the background all the time in the same way it does for checking your local media as a) it is likely too slow given the number of network requests and b) all the bandwidth usage literally costs me money so I’d end up paying more than people paid for the app (especially if they bought it on sale 6 years ago when it first launched). I don’t really want to do subscription pricing for this sort of thing so I think the only option is to have the check be manual from within the app and perhaps limited to once per day. That way you can go and see what songs have been updated when you think to do it and there isn’t wasted bandwidth being used in the background by every user. Perhaps in the future I could look to adding a cheap subscription for those users who do want to have automatic notifications but that’s definitely for much further in the future.

So, as you can see there is plenty to think about. I’m going to tinker with a few bits in the database later this week in order to get the basic matching working within the app and then I can evaluate how easy or difficult the other pieces will be. My aim is to provide a TestFlight link next issue (14th December 2022) that will let you scan your music and see which tracks have Spatial Audio, hopefully with automatic playlist creation as well!

Related Links

What is Spatial Audio? - A good primer from Digital Trends.
Spatial Audio Finder - My tool which allows you to search for an artist and see which songs are currently supported by Spatial Audio.
@NewSpatialAudio - Another one of my tools, this one tweets whenever a new Spatial Audio track is found on Apple Music.

Animated Artwork on Apple Music

Apple added support for animated artwork within Apple Music towards the end of 20206. Getting access to that artwork was the number one requested feature for my Apple Music Artwork Finder and I was finally able to get it working last month.

Normally I’d do some network sniffing to determine what is going on but the Apple Music clients are all protected with SSL pinning which prevents me from seeing what data is being fetched. Thankfully, the Apple Music website also shows the animated artwork and I was able to view the source code to see where it was coming from.

The website uses JavaScript to load in the video artwork after the page has finished loading; this is a pain as my server can only view the page as it is initially rendered before that extra network request. Luckily, whilst digging through the HTML code I was able to find an embedded JSON string which contained links to the .m3u8 playlist that loads the actual videos. All I needed to do was loop through the various urls and then rip out the link to the highest resolution video7.

Unfortunately this stopped working last week8 as Apple had updated their code to remove that embedded JSON string 🤦🏻‍♂️. I thought that would be the end of this feature but they’ve actually made it slightly easier by adding an <amp-ambient-video> tag which links directly to the video playlist. With a quick fix in place to extract the source from that, everything was back to working 🎉.

You can start downloading animated artwork now with the Apple Music Artwork Finder.

Roadmap

The roadmap is my way of staking what I’m going to do over the next 2 weeks.

1st December - 14th December (Issue #2)

As mentioned earlier, I need to get the final part of the Spatial Audio matching working with my Music Library Tracker app. A TestFlight beta will be available in the next issue!
Return to Dark Tower is a board game that comes with a physical Bluetooth connected tower and an iPad app that runs several facets of the game. It’s very cool (in a distinctly nerdy way). I’ve built a helper app which you can run in a Slide Over panel on iPad to keep track of your cards and Wild Advantages, I just need to put some screenshots together and submit it to the App Store.
I’ve been using a Stream Deck for the past few months as a way to manage my freelance projects and build tools. I started writing an article about the process but I need to finish it off and publish it.
Over the past year I’ve been working on porting Ink into a nice Swift package. I don’t think this will be done in the next 2 weeks but I want to at least revisit it as it feels like something I could finish off over the Christmas period.

That wraps it up for this issue. I hope you found something of interest! Feel free to recommend the newsletter to your friends, family, and colleagues.

You can always comment on this issue directly or email me via ben@bendodson.com

The Dodo Developer

#1: Catacombs, Spatial Audio, and Animated Album Artwork

Prototyping a new dice mechanic for an adventure game and talking about Spatial Audio / animated artwork on Apple Music.

Contents

Catacombs

Spatial Audio Matching

Animated Artwork on Apple Music

Recommended Links

Music

Video Games

Board Games

Podcasts

Books

Roadmap

1st December - 14th December (Issue #2)

Discussion about this post