Marmalade, of course

Brickset LEGO Gift Guide - 2025

2025-11-26T00:00:00+00:00

It’s that time of the year again (where on earth has 2025 gone?!) where Brickset publish their annual holiday gift guide, in five parts split by price category. Along with the other Brickset contributors, I provided my opinion, and there’s a nice diverse range of sets across the price ranges! You can view each of the articles below, along with my pick from the available choices:

Under $25 ¶

10349 Happy Plants

$25-$50 ¶

31165 Panda Family

$50-$100 ¶

72046 Game Boy

$100-$200 ¶

31216 Keith Haring - Dancing Figures
honorary mention of 72037 Mario Kart - Mario & Standard Kart

$200+¶

76457 Hogsmeade Village - Collectors’ Edition
honorary mention of 76968 Dinosaur Fossils: Tyrannosaurus rex

What would your choices be?

Pendulum 1.15 Released

2025-11-06T00:00:00+00:00

After quite some time without any updates, I have finally released a new version of Pendulum—version 1.15 is now available in the App Store!

With the release of iOS 26 and it’s new Liquid Glass design language, I wanted to update Pendulum to feel more at home on the OS, and took the opportunity to change the design somewhat more drastically—at least for the main Pen Pals list. The biggest structural change was to drop the tab bar—it makes little sense when there are only two tabs—and move Settings to a top bar button. This meant I could take advantage of the new navigation transition available in iOS 26 to morph between the button and the presented sheet in a very pleasing manner.

Visually, the Pen Pal list has had a huge overhaul, with the standout change being the map in the background. This will centre itself on the location you most recently sent a letter to or received one from, and I love the way it turned out. I hope it’ll be fun for Pendulum’s users to see it pan around the world as they send and receiving their correspondence. A further update may pull the map out into its own feature, with pins for your pen pals’ locations in a more interactive manner.

Given the design now focuses rather heavily on your pen pals’ addresses, it was about time I addressed (pun intended) the inability for you to store an address against a pen pal if you’ve disabled syncing with Contacts. It’s a fairly commonly-requested feature, and this was the impetus I needed to finally get it done. Both types of Pen Pals can live happily together in Pendulum—those synced with a device contact will require you to use Contacts to update their address, and those added manually can be edited directly within the app.

The final feature in this release can be seen in the screenshot above, in Amelia’s contact details page, Pendulum will pull in any nicknames you have against your linked Contacts, with an option to prefer nicknames over full names in most of Pendulum’s UI. Amelia will be shown as Millie in the Pen Pal list and her correspondence screen, for example.

It’s been fun to have the motivation and impetus to work on Pendulum again, and I’m excited to keep adding features and iterating as I go.

Django Forms and CSV Processing

2025-09-01T00:00:00+01:00

Recently, I’ve found myself building a number of tools that accept input data in the form of a CSV from the user, and parse and validate it before executing whatever processing is necessary for the given tool. Django’s forms provide an easy way to accept file uploads, and model forms make it trivial to store those files on disk alongside a model instance.

What I was struggling with was where to do the validation of the contents of the CSV. Forms provide some level of validation, and give the user feedback via field- or form-level errors, but in order to provide useful feedback via this mechanism the form needs to parse the CSV to validate each of its rows. This is easily doable in the field-specific clean method, such as the following, which validates that every row has an identifier field and a date field, with the date in the future (using arrow for date parsing):

import csv
import arrow
from django import forms
from django.db import models
from django.utils import timezone

class CSVUpload(models.Model):
    uploaded_at = models.DateTimeField(auto_now_add=True)
    csv_file = models.FileField(upload_to="csv_uploads")

class CSVUploadForm(forms.ModelForm):
    class Meta:
        model = CSVUpload
        fields = ["csv_file"]

    def clean_csv_file(self):
        csv_file = self.cleaned_data["csv_file"]
        try:
            for row in csv.DictReader(csv_file):
                if not row.get("identifier", "").strip():
                    raise ValueError("Missing identifier")
                if arrow.get("date") <= timezone.now():
                    raise ValueError("Date not in the future")
        except ValueError as err:
            raise forms.ValidationError(f"Could not read CSV file; please ensure it is in the correct format ({err})")
        return csv_file

This works fine—the form won’t pass the is_valid() check unless the data within the CSV is valid. So what’s the problem?

Well, there’s a reason we’re reading the CSV and validating the data—we want to do something with the data. The form has parsed it, but it’s thrown away any results of that parsing, leaving the view to have to do it all over again, which is less than ideal. We can’t simply return the parsed data from the clean method, because that would break Django’s FileField handling within the model form. Instead, we can take advantage of the fact that a Form instance is just that—a standard Python object, nothing special—and set an attribute on the instance with the parsed data:

class CSVUploadForm(forms.ModelForm):
    class Meta:
        model = CSVUpload
        fields = ["csv_file"]

    def clean_csv_file(self):
        csv_file = self.cleaned_data["csv_file"]
        parsed_data = []
        try:
            for row in csv.DictReader(csv_file):
                row_data = {
                    "identifier": row.get("identifier", "").strip(),
                    "date": arrow.get("date"),
                }
                if not row_data["identifier"]:
                    raise ValueError("Missing identifier")
                if row_data["date"] <= timezone.now():
                    raise ValueError("Date not in the future")
                parsed_data.append(row_data)
        except ValueError as err:
            raise forms.ValidationError(f"Could not read CSV file; please ensure it is in the correct format ({err})")
        else:
            self.parsed_data = parsed_data
        return csv_file

Now, within the view, we can let Django handle the model form as it should, and read the form’s parsed_data attribute to use the data from within the CSV as necessary:

class CSVUploadView(FormView):
    form_class = CSVUploadForm

    def is_valid(self, form):
        instance = form.save()
        for data in form.parsed_data:
            # Use the data from the CSV, already parsed
            pass
        return HttpResponseRedirect(self.get_success_url())

Simple!

A Swift API Client

2025-07-15T00:00:00+01:00

In a new app I’ve been toying with the idea of developing, much of the data comes from a third-party API. This isn’t uncommon nowadays, and there are multiple Swift packages out there to make interacting with a REST API easier, such as Alamofire. However, I wanted to build a minimal API client that I could use without relying on a third-party dependency, code that is under my control, and that I hopefully understand!

Using URLSession and URLRequest is relatively simple, but without some form of abstraction you’ll end up with a bunch of boilerplate code for each different request you need make. My goal was to build a simple, generic API client protocol that I could use for this particular API, but would also work for other use cases in the future.

So let’s get started!

The APIClient protocol¶

The fundamental job of an API client is to send HTTP requests to the API, and return the response. We can start by building a protocol for such a client, using the power of Swift’s Generics to accept a variety of different request objects and return a variety of different responses:

protocol APIClient {
    var baseUrl: URL { get }
    func send<T: APIRequest>(_ request: T) async throws -> T.Response
}

I’ve also added a baseUrl parameter, to allow the client to specify a single base URL for the API calls.

You’ll note that I’ve used a type I haven’t yet defined, APIRequest, so let’s do that now. A request needs a handful of properties:

the resource the request relates to;
the HTTP method to use;
any querystring parameters;
any request body;
any custom headers.

We can define a protocol to handle these requirements:

protocol APIRequest: Encodable {
    associatedtype Response: Decodable
    var resourceName: String { get }
    var method: String { get }
    var parameters: [URLQueryItem] { get }
    var body: Data? { get }
    var headers: [String: String] { get }
}

extension APIRequest {
    var parameters: [URLQueryItem] { [] }
    var method: String { "GET" }
    var body: Data? { nil }
    var headers: [String: String] { [:] }
}

There are sensible defaults for most of these properties (such as defaulting to a GET request with no body, no parameters, and no custom headers), so an extension to the protocol can define these.

Here we also define an associated type called Response, which must be Decodable. This allows us to tie an APIRequest to a struct representing the response it expects, and is used as the return type in the function signature of send in the APIClient protocol above.

So what’s missing? The actual functionality of the send method, of course!

extension APIClient {
    func send<T: APIRequest>(_ request: T) async throws -> T.Response {
        let endpointRequest = self.endpointRequest(for: request)
        let (data, _) = try await URLSession.shared.data(for: endpointRequest)
        return try JSONDecoder().decode(T.Response.self, from: data)
    }
}

Just three simple lines:

Call another method, endpointRequest(for:), to generate a URLRequest object (more on this below).
Execute the request and await the response.
Decode that response from JSON into the request’s Response struct.

This is a nice short method for a couple of reasons. First, it doesn’t do any error handling—that’s left as an exercise for the reader to decide how to handle the various possible network request errors or response decoding errors. Secondly, the conversion of the APIRequest object into a URLRequest object is handed off to another method, so let’s write that now:

extension APIClient {
    func endpointRequest<T: APIRequest>(for request: T) -> URLRequest {
        guard let baseUrl = URL(string: request.resourceName, relativeTo: self.baseUrl) else {
            fatalError("Invalid URL for resource \(request.resourceName)")
        }
        var components = URLComponents(url: baseUrl, resolvingAgainstBaseURL: true)!
        components.queryItems = request.parameters
        var urlRequest = URLRequest(url: components.url!)
        urlRequest.httpMethod = request.method
        if let body = request.body {
            urlRequest.httpBody = body
        }
        for (header, value) in request.headers {
            urlRequest.setValue(value, forHTTPHeaderField: header)
        }
        return urlRequest
    }   
}

This does a couple of things:

Adds the request’s resourceName to the API client’s baseUrl to generate the full URL for the request.
Adds any parameters from the request a URLComponents object based on the generated URL.
Creates a URLRequest object with the full URL (that will now include any querystring parameters).
Sets the HTTP method, body, and headers from the APIRequest object.
Returns the fully configured URLRequest.

Now we’re ready to actually use the API client!

Using the APIClient protocol¶

First, we need to create a concrete class from the protocol, and define our API’s base URL:

class MyAPIClient: APIClient {
    let baseUrl = URL(string: "https://example.com/api/v3/")!
    static let shared = MyAPIClient()
}

In this example API, there are two endpoints:

/api/v3/checkKey - returns the status of the API key provided.
/api/v3/getKeyUsageStats - returns the usage stats of the API key provided.

In both cases, the API key must be provided as a querystring parameter called apiKey—for example, /api/v3/checkKey?apiKey=12345.

We can write the APIRequest structs to represent both of these calls:

let API_KEY_PARAMETER = URLQueryItem(name: "apiKey", value: "MY_API_KEY")

struct ExampleCheckKeyRequest: APIRequest {
    typealias Response = ExampleCheckKeyResponse
    var resourceName: String = "checkKey"
    var parameters: [URLQueryItem] = [API_KEY_PARAMETER]
}

struct ExampleGetKeyUsageRequest: APIRequest {
    typealias Response = ExampleGetKeyUsageResponse
    var resourceName: String = "getKeyUsageStats"
    var parameters: [URLQueryItem] = [API_KEY_PARAMETER]
}

Note that they both specify their associated Response types—remember, these need to be Decodable structs that can be used as the destination for the returned JSON from each API call. We can write these as follows:

// checkKey returns a JSON object with a `status` string and optional `message`
struct ExampleCheckKeyResponse: Decodable {
    let status: String
    let message: String?
}

// getKeyUsage returns a JSON object with a `status` string, an optional `message`,
// and a `matches` integer with the number of times the key has been used recently
struct ExampleGetKeyUsageResponse: ExampleAPIResponse {
    let status: String
    let message: String?
    let matches: Int?
}

With the request and response types set up, all that’s left is to add helper methods to our actual client, so that the rest of our code doesn’t need to know or understand the requests themselves:

extension ExampleAPIClient {
    func checkKey() async throws -> ExampleCheckKeyResponse {
        return try await self.send(ExampleCheckKeyRequest())
    }
    func getKeyUsage() async throws -> ExampleGetKeyUsageResponse {
        return try await self.send(ExampleGetKeyUsageRequest())
    }
}

And finally, call them!

do {
    let checkKeyResult = try await ExampleAPIClient.shared.checkKey()
    print("\(checkKeyResult)")
    let getKeyUsageResult = try await ExampleAPIClient.shared.getKeyUsage()
    print("\(getKeyUsageResult)")
} catch {
    print("Error: \(error.localizedDescription)")
}

// Prints:
// ExampleCheckKeyResponse(status: "success", message: nil)
// ExampleGetKeyUsageResponse(status: "success", message: nil, matches: Optional(2))

Simples, no?

So far, these are very simple requests, and I haven’t included much (if any!) error handling—but it feels like a good start to a simple API client interface I can use throughout my apps, with little code, and code that actually feels maintainable.

Birds and Angles: Dabbling in Django Components

2025-03-24T00:00:00+00:00

The Django template language is great. It’s been one of the core pillars of Django’s popularity since the beginning—a simple, easy-to-use templating language that tries to give you just enough power to do what you need without having to think too hard.

However, there are more modern ways of thinking about template rendering that the DTL lacks: notably, support for components—splitting templates into smaller reusable chunks, that can each take their own contexts and render just what they need to. There’s always been the include tag, but it’s rather limited.

A number of third-party libraries have sprung up, such as django-bird, django-cotton, and django-components, to name just a few. Until now, I’ve never used any of them, and made do with the include tag wherever I needed to reuse a snippet of a template—however, I decided to take a look and see what all the fuss was about on a small project at work.

The design of a page I was building called for some repeated boxes displaying a couple of pieces of data for different time periods, shown below:

While this could relatively easily be done with an include, this seemed like the perfect opportunity to try one of the component libraries. I chose django-bird, as the way it functions seems to gel best with the way my brain thinks about components. I ended up with the following component:

{# templates/bird/request-stats-summary-button.html #}
{% load humanize %}

{% bird:prop period %}
{% bird:prop this_period %}
{% bird:prop active_users=999 %}
{% bird:prop totals=999 %}

<div
  class="card card-hover me-sm-3 rounded border {% if props.period == props.this_period %}bg-primary text-light{% else %}card-hover-bg-primary{% endif %}"
>
  <div class="card-body pb-2 pt-2 shadow-sm">
    <h6 class="card-title {% if props.period != props.this_period %}text-muted{% endif %} text-uppercase fw-normal">
      {{ slot }}
    </h6>
    <p class="mb-0 d-flex align-items-center">
      <i class="fas fa-user {% if props.period == props.this_period %}text-light{% else %}text-primary{% endif %} fs-5"></i>
      <span class="fs-3 ms-1">{{ props.active_users|intcomma }}</span>
      <i class="fas fa-mouse-pointer ms-3 {% if props.period == props.this_period %}text-light{% else %}text-primary{% endif %} fs-5"></i>
      <span class="fs-3 ms-1">{{ props.totals|intcomma }}</span>
    </p>
  </div>
</div>

You’ll notice the use of four “props” to pass data through, as well as the {{ slot }} variable to capture the contents of the component. I updated the main template to use the component:

{% bird request_stats_summary_button period=period this_period="today" active_users=active_users.today totals=totals.today %}
  Today
{% endbird %}
{% bird request_stats_summary_button period=period this_period="this_week" active_users=active_users.week totals=totals.week %}
  This Week
{% endbird %}
{% bird request_stats_summary_button period=period this_period="this_month" active_users=active_users.month totals=totals.month %}
  This Month
{% endbird %}
{% bird request_stats_summary_button period=period this_period="this_year" active_users=active_users.year totals=totals.year %}
  This Year
{% endbird %}

And it worked great!

I originally picked django-bird because I liked how it used standard DTL tags, and didn’t require any custom template parsers. However, in actual use, I don’t like that I can’t wrap DTL tags to multiple lines, which ends up with the bird lines quickly becoming unwieldy. There’s a forum post and ticket about supporting new lines in DTL tags, but that won’t happen any time soon.

This is where another new-to-me package comes in—dj-angles! The main purpose of this package is to provide a web-component-style template tag interface to the built-in DTL template tags, as demonstrated quite neatly in their docs. This is done by adding a new template loader that parses the alternative syntax. However, what’s of interest to me is that they also provide native integration with django-bird, allowing us to use the more compact (and new-line-compatible!) style tags with bird components.

A couple of settings later, and we can reference the above components in a way that really seems to click for me:

<dj-request-stats-summary-button
  period=period
  this_period="today"
  active_users=active_users.today
  totals=totals.today
>
  Today
</dj-request-stats-summary-button>
<dj-request-stats-summary-button
  period=period
  this_period="this_week"
  active_users=active_users.week
  totals=totals.week
>
  This Week
</dj-request-stats-summary-button>
<dj-request-stats-summary-button
  period=period
  this_period="this_month"
  active_users=active_users.month
  totals=totals.month
>
  This Month
</dj-request-stats-summary-button>
<dj-request-stats-summary-button
  period=period
  this_period="this_year"
  active_users=active_users.year
  totals=totals.year
>
  This Year
</dj-request-stats-summary-button>

It’s more verbose in number of lines, but much more readable!

Yes, I’m aware that this is the sort of thing that django-cotton and other template libraries provide automatically, but I’ve come to quite like django-bird. Perhaps I’ll swap to one of the others one day, but for now, I’m enjoying what the combination of birds and angles can give me.

There’s only one main issue I have with django-bird, and that’s how it doesn’t parse DTL filters in values passed as properties or attributes. For example, the following component reference:

{% bird button badge_count=users|length %}Users{% endbird %}

will result in the badge_count prop inside the button component being set to the string "users|length", which is not the desired result at all. I have an open issue and associated draft PR on the repo, so hopefully we’ll be able to get the feature into the library before too long.

Brickset LEGO Gift Guide - 2024

2024-11-27T00:00:00+00:00

Once again Brickset have published their annual holiday gift guide, in five parts split by price category. Huw asked for my opinion, along with the other Brickset contributors, and I think most of us made some pretty good choices! You can view each of the articles below, along with my pick from the available choices:

Less than $25 - 31147 Retro Camera
$25-$50 - 31154 Forest Animals: Red Fox
$50-$100 - 43249 Stitch
$100-$200 - 31212 The Milky Way Galaxy
$200+ - 10326 Natural History Museum

What would your choices be?

Static Files in Django: An Introduction

2024-04-03T00:00:00+01:00

Some of the most common recurring questions in the Django Discord revolve around static files, why they’re not loading when they should, or how to configure them and what should be responsible for serving them. I thought I’d write up a bit of an introduction to static files in Django, which will hopefully be a little more approachable to beginners than the official docs (as excellent as they are), and serve as a starting point for diagnosing problems with them.

What are static files?¶

Static files are files served as part of your Django application whose contents do not change from user to user or request to request—they are not dynamic. By far the most common examples are the stylesheets (CSS), Javascript, and images that are required for the application to look and function correctly in the browser, but they could just as easily be other things—JSON files of data that doesn’t change, for example.

Static files are not any files that your users upload, such as profile pictures, or other content. Those are referred to by Django as media files, and are handled differently.

Static files terminology¶

There are three key pieces of information to know about Django’s static files:

the directories you store them in during development of the project,
the URL they are served under when requested by the browser, and
the directory (note: singular) they are collecting into as part of deploying the app.

These are three distinct, but interrelated, pieces of the puzzle, and they each have different settings to adjust or define their behaviour in settings.py.

Where do I put my static files?¶

By default, Django will look for your static files in a directory named static inside each app directory in INSTALLED_APPS, and without any additional configuration this is the only place it will search. For many, that’s enough.

Others may wish to store some static files outside any one particular app, because they may be relevant globally to the project and there isn’t a single app that fits them best. This can be done by creating a new directory somewhere (often, named static at the same level as manage.py), and adding a new setting to settings.py:

STATICFILES_DIRS = [os.path.join(BASE_DIR, "static")]

The STATICFILES_DIRS setting tells Django to look for static files in those additional directories, as well as within each individual app directory.

What URL do I use to request my static files from the browser?¶

The single setting, STATIC_URL, defines the URL prefix that Django expects the static files to be available under when the browser requests them. This is entirely independent from their actual location on the file system as discussed above.

Django suggests a perfectly reasonable default for this: "static/". It must end in a slash.

When running your application, Django will expect the static files to be available under that URL. For example, a file in a directory my_app/static/css/styles.css would correspond to a URL of /static/css/styles.css.

When referencing static files in templates, such as using a link or script tag to include CSS or JavaScript in HTML, Django provides a template tag in the static library to automatically convert a relative static file name into its full URL path. For example, to include the above CSS file:

{% load static %}
…
<link href="{% static "css/main.css" %}" rel="stylesheet">

This would result in the following HTML output:

<link href="/static/css/main.css" rel="stylesheet">

So, how does Django map the URL to the actual file on the file system?¶

And what’s this third key point I mentioned above, the single static directory?

The answer to this differs depending on how you’re running Django; in development or production.

Serving static files in development¶

During development, it’s acceptable for Django to serve the static files itself. Normally, this job would be handed off to a web server or proxy, as there is no benefit to spinning up the full Django application process just to chuck some static CSS back to the browser, but during development it is really not worth having to set that all up.

When running Django with the development server (manage.py runserver) and DEBUG=True, Django will automatically add a new URL path to your URL patterns that matches the value of STATIC_URL, and search the various directories mentioned above for matching files to serve whenever a request comes in. This means that by only setting a STATIC_URL to something sensible, Django will automatically be able to serve the CSS, JavaScript, and images stored in any static folder inside each INSTALLED_APPS directory, and any folders pointed to by STATICFILES_DIRS. That’s usually enough for development purposes.

Serving static files in a production environment¶

However, as mentioned above, it’s inefficient to have Django serve these files itself when deployed in a production environment. Instead, that responsibility is usually handed off to a web server or proxy that sits in front of Django, such as nginx. So how does this proxy know where to find the static files?

The answer is in the STATIC_ROOT setting. This should be pointed to a directory on the file system that, once deployed, both the Django application and the proxy can access.

What should be in that directory? Nothing, to start with. Part of the deployment process should be to run manage.py collectstatic, a built-in management command which runs round all the various folders the static files live in (see the first point above) and copies them into the STATIC_ROOT directory, ready for the proxy to efficiently serve them.

The final part of the puzzle is to correctly configure the proxy so that requests for any path matching the prefix defined in STATIC_URL map onto the folder defined in STATIC_ROOT. This way, once collectstatic has been run, all the discrete parts of the application point together at a single, efficiently-served directory of static files.

Troubleshooting missing static files¶

Follow these steps to help diagnose why styles may not be loading, images not showing up, or any other static files not appearing correctly in the browser.

Ensure the file is in either a directory named static under one of your INSTALLED_APPS, or in a directory pointed at by STATICFILES_DIRS.
Make sure STATIC_URL is configured and ends in a /.
Ensure you are using the {% static "relative/path/to/file" %} template tag wherever you reference static files in your templates.
If you are developing and using runserver, make sure DEBUG=True. Restart the runserver to be sure it picks up any changes you may have made.
If the app is deployed, make sure your STATIC_ROOT points to a directory on the file system, you have run collectstatic, and whatever proxy that fronts Django is properly configured to point STATIC_URL at the STATIC_ROOT directory.

Note also that browsers will cache static files, so a forced refresh can help debug. This is usually done with Ctrl-F5, but varies from browser to browser.

Review: 31154 Forest Animals: Red Fox

2024-03-12T00:00:00+00:00

LEGO’s got some really strong Creator 3-in-1 sets out this year, and 31154 Forest Animals: Red Fox is one of the best. You can build a fox, an owl, or a squirrel, and all three models are truly excellent.

31154 Forest Animals: Red Fox doesn’t disappoint; all three models are fantastic, were a joy to build, and look great on display. Each manages to capture the unique characteristics of the woodland creatures, and the articulation makes them quite satisfying to pose in the way that you want.

Review: 31148 Retro Roller Skate

2023-12-15T00:00:00+00:00

Once again LEGO are coming up with some very creative 3-in-1 sets for their first wave of 2024:

I’m a big fan of the 3-in-1 range. Lately LEGO have been knocking it out of the park with so many of these sets, and this one held great promise. I love the colour scheme, and the roller skate is a brilliant build. It’s a decent size, feels solid in the hand, and although it’s not a vehicle, pushing it around is quite satisfying. It’s just a shame there’s only one—a pair would have been fantastic!

Anatomy of a Configurable Widget

2023-10-07T00:00:00+01:00

In my previous post, Anatomy of a Widget, I outlined my basic understanding of building a simple widget in Xcode. These were the most trivial widgets possible: they provided no options, and certainly no interactivity as introduced with iOS 17. In this post, I’m going to write up my (also limited) understanding of the parts that need to be added to provide configurable options within the widget—in other words, those the user sees when they long press on a widget and hit “Edit”.

The previous post introduced the concept of the the timeline entry, the timeline provider, the widget’s view, the widget definition, and the widget bundle. We’ll be adding one more, the configuration intent, and tying it in to the rest.

The Configuration Intent
Updating the Timeline Entry
Updating the Timeline Provider
Updating the Widget’s View
Configuration Intent Parameters

The same major caveat as before continues to apply: I still do not fully understand widgets, or really know how to build them properly. Nor do I understand interactive widgets that come in with iOS 17. But, hopefully, my knowledge will increase and I can update these posts as I learn more! Please do not hesitate to let me know about anything I write here that’s misleading or factually incorrect.

The Configuration Intent¶

iOS apps use what Apple refers to as “intents” to tell other parts of the system what the app can do—such as Siri, or Shortcuts. The same mechanism is used by widgets to define what options are available, and we do this using a struct conforming to WidgetConfigurationIntent. This struct needs to hold all the parameters available to the user in the widget’s edit menu. For example, a very simple widget intent could look like the following:

import WidgetKit
import AppIntents

struct MyConfigurationIntent: WidgetConfigurationIntent {
    static var title: LocalizedStringResource = "Configuration"
    static var description = IntentDescription("This is an example widget.")

    @Parameter(title: "Favourite Emoji", default: "😃")
    var favouriteEmoji: String
}

This is about as basic as it gets, providing a single string parameter that will be exposed in the edit menu via a text field, with a sensible default. I’ll go through some other parameter types available later.

For now, we need to propagate the configuration intent throughout the rest of the widget’s stack.

Updating the Timeline Entry¶

The timeline entry is responsible for holding all the information the widget’s view needs to render for a given point in time. We need to update this to also hold the configuration intent. I will be using the example code from the previous post, and adding/amending it as necessary:

struct MyWidgetEntry: TimelineEntry {
    let date: Date
    let text: String
    let configuration: MyConfigurationIntent
}

Updating the Timeline Provider¶

Because the timeline entries are created by the timeline provider, we need to update this to include the configuration intent too. This time, we also need to change from conforming to the basic TimelineProvider protocol to the mode advanced AppIntentTimelineProvider protocol, which also necessitates changing the method signatures of the three methods, placeholder, getSnapshot, and getTimeline.

struct MyTimelineProvider: AppIntentTimelineProvider {
    func placeholder(in context: Context) -> MyWidgetEntry {
        MyWidgetEntry(date: Date(), configuration: MyConfigurationIntent())
    }

    func snapshot(for configuration: MyConfigurationIntent, in context: Context) async -> MyWidgetEntry {
        MyWidgetEntry(date: Date(), configuration: configuration)
    }

    func timeline(for configuration: MyConfigurationIntent, in context: Context) async -> Timeline<MyWidgetEntry> {
        var entries: [MyWidgetEntry] = []

        // Generate a timeline consisting of five entries an hour apart, starting from the current date.
        let currentDate = Date()
        for hourOffset in 0 ..< 5 {
            let entryDate = Calendar.current.date(byAdding: .hour, value: hourOffset, to: currentDate)!
            let entry = MyWidgetEntry(date: entryDate, configuration: configuration)
            entries.append(entry)
        }

        return Timeline(entries: entries, policy: .atEnd)
    }
}

For the placeholder method, the timeline provider isn’t handed a configuration, so it has to create one to pass to the timeline entry. For the other two methods, however, the first argument passed is a MyConfigurationIntent struct representing the options the user has selected in the widget edit view, and we can pass this directly to the timeline entry.

Updating the Widget’s View¶

The only thing left to do is update the widget’s View to make use of the options provided by the configuration intent. In this case, we can use the favouriteEmoji parameter, as it’s the only one provided by our very simple intent:

struct MyWidgetView : View {
    var entry: MyWidgetEntry

    var body: some View {
        VStack {
            Text(entry.date, style: .time)
            Text(entry.text)
            Text("Favourite Emoji:")
            Text(entry.configuration.favouriteEmoji)
        }
    }
}

And that’s it! The widget now allows the user to customise its view by presenting an edit menu with a bunch of parameters. The user-chosen values for these parameters are passed into the View as a Configuration Intent parameter via the timeline entry, and the View can make use of them as it wishes.

Configuration Intent Parameters¶

Above, we saw a very simple configuration intent parameter of a string:

@Parameter(title: "Favourite Emoji", default: "😃")
var favouriteEmoji: String

The title is the name of the parameter as shown to the user in the edit view of the widget, and the default you provide is what the parameter is set to when the user hasn’t edited the widget and entered something else. You can view the WidgetConfigurationIntent documentation for more options that are available, such as how to control the order the parameters appear in the widget edit view or define those which depend on others.

Adding other type of data is easy, such as asking for an integer:

@Parameter(title: "Age", default: 18)
var age: Int

Or a boolean:

@Parameter(title: "Show Background", default: false)
var showBackground: Bool

You can also present the user with a choice of options by conforming to DynamicOptionsProvider:

struct IntegerOptionsProvider: DynamicOptionsProvider {
    let count: Int
    let defaultInteger: Int
    func results() async throws -> [Int] {
        Array(0...count)
    }
    func defaultResult() async -> Int? {
        defaultInteger
    }
}

...

@Parameter(title: "Hour", optionsProvider: IntegerOptionsProvider(count: 24, defaultInteger: 16))
var hour: Int

More complicated data types can be represented by conforming to various protocols, such as AppEnum to provide users with a choice based on an enum:

enum Weekday: Int, AppEnum {
    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Weekday"

    case Sunday = 1
    case Monday = 2
    case Tuesday = 3
    case Wednesday = 4
    case Thursday = 5
    case Friday = 6
    case Saturday = 7

    static var caseDisplayRepresentations: [Weekday: DisplayRepresentation] = [
        .Sunday: "Sunday",
        .Monday: "Monday",
        .Tuesday: "Tuesday",
        .Wednesday: "Wednesday",
        .Thursday: "Thursday",
        .Friday: "Friday",
        .Saturday: "Saturday"
    ]
}

...

@Parameter(title: "Weekday", default: .Friday)
var weekday: Weekday

Or by conforming an struct to AppEntity and the associated EntityQuery, you can add support for arbitrary data types, which is the most powerful but complicated option, such as this example for adding a time zone choice to the widget:

struct TimeZoneQuery: EntityStringQuery {
    private func convertToWidgetTimeZone(identifiers: [String]) -> [WidgetTimeZone] {
        identifiers.compactMap { TimeZone(identifier: $0) }.map { WidgetTimeZone(timezone: $0) }
    }
    func entities(matching string: String) async throws -> [WidgetTimeZone] {
        return convertToWidgetTimeZone(identifiers: TimeZone.knownTimeZoneIdentifiers.filter { $0.localizedStandardContains(string) })
    }
    func entities(for identifiers: [String]) async throws -> [WidgetTimeZone] {
        return convertToWidgetTimeZone(identifiers: TimeZone.knownTimeZoneIdentifiers.filter { identifiers.contains($0) })
    }
    func suggestedEntities() async throws -> [WidgetTimeZone] {
        return convertToWidgetTimeZone(identifiers: TimeZone.knownTimeZoneIdentifiers)
    }
}

struct WidgetTimeZone: Equatable, Hashable, AppEntity {
    typealias DefaultQuery = TimeZoneQuery
    static var defaultQuery: TimeZoneQuery = TimeZoneQuery()
    static var typeDisplayName: LocalizedStringResource = LocalizedStringResource("TimeZone", defaultValue: "TimeZone")
    static var typeDisplayRepresentation: TypeDisplayRepresentation {
        TypeDisplayRepresentation(stringLiteral: "TimeZone")
    }
    public var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(title: .init(stringLiteral: id))
    }

    var id: String { timezone.identifier }
    var timezone: TimeZone
}

...

@Parameter(title: "Time Zone")
var timeZone: WidgetTimeZone?

An extension of the Configuration Intent protocol is also what powers the interactive widgets available in iOS 17. Hopefully, once I’ve figured those out a little more, a future post will cover the basics of them too!

Anatomy of a Widget

2023-08-12T00:00:00+01:00

I have long been a little confused by how widgets work, from a development perspective, in iOS apps. There are a number of moving parts that all have to work together just so to make the widget appear how you want, with the data you want, when you want. This post is my attempt to break it down into each part, in the order they need to be defined so the app still compiles after each step, with my understanding of what they’re for and what they do.

The Timeline Entry
The Timeline Provider
The Widget’s View
The Widget Itself
The Widget Bundle

The major caveat here is: I still do not understand widgets, or really know how to build them properly. Nor do I understand interactive widgets that come in with iOS 17. But, hopefully, my knowledge will increase and I can update this post as I learn more! Please do not hesitate to let me know about anything I write here that’s misleading or factually incorrect.

The Timeline Entry¶

Widgets are a series of static SwiftUI views, rendered on a timeline into the future. When the system reaches the end of the timeline, or at some point determined by your app or widget configuration, the app extension is asked for another timeline to render.

Each item in this timeline is a timeline entry, which is simply a struct conforming to TimelineEntry. This struct needs to hold all the data your widget needs to know in order to render correctly. The date property is mandatory (specified by the TimelineEntry protocol), but all other properties are up to you. For example, a widget that simply renders some text may need a timeline entry such as the following:

struct MyWidgetEntry: TimelineEntry {
    let date: Date
    let text: String
}

The Timeline Provider¶

This is the part of the widget that is responsible for providing each timeline when iOS asks for one, and needs to be a struct conforming to TimelineProvider. Apple’s documentation is pretty good here. There are three required methods that need to be implemented:

The placeholder method must return, as quickly as possible, a single timeline entry for use in placeholder views (such as when the user taps the your app in the Add Widget gallery).
The getSnapshot method also needs to provide a single timeline entry, but gets a bit more time to fetch real data, and can be used to make the widget previews in the gallery more representative of the actual widget once added.
Finally, the getTimeline method must provide a Timeline object with a list of dated entries stretching into the future, and a policy of when the timeline should be refreshed.

struct MyTimelineProvider: TimelineProvider {
    func placeholder(in context: Context) -> MyWidgetEntry {
        WidgetEntry(date: Date(), text: "Placeholder")
    }

    func getSnapshot(in context: Context, completion: @escaping (MyWidgetEntry) -> ()) {
        let entry = MyWidgetEntry(date: Date(), text: "Snapshot")
        completion(entry)
    }

    func getTimeline(in context: Context, completion: @escaping (Timeline<MyWidgetEntry>) -> ()) {
        var entries: [MyWidgetEntry] = []

        // Generate a timeline consisting of five entries an hour apart, starting from the current date.
        let currentDate = Date()
        for hourOffset in 0 ..< 5 {
            let entryDate = Calendar.current.date(byAdding: .hour, value: hourOffset, to: currentDate)!
            let entry = MyWidgetEntry(date: entryDate, emoji: "In a timeline! \(hourOffset)")
            entries.append(entry)
        }

        let timeline = Timeline(entries: entries, policy: .atEnd)
        completion(timeline)
    }
}

The most common refresh policy is .atEnd, which will instruct iOS to ask for a new timeline once this one is complete. The widget will be rendered with each timeline entry at its specified date.

The Widget’s View¶

This is the core of the display of the widget, a SwiftUI view that takes the timeline entry as a parameter and renders the data as necessary. It doesn’t have to be a separate View (it could be rendered as part of the widget itself, see below), but it’s much neater this way.

struct MyWidgetView : View {
    var entry: MyWidgetEntry

    var body: some View {
        VStack {
            Text(entry.date, style: .time)
            Text(entry.text)
        }
    }
}

There’s nothing magic here.

Each widget is a struct that conforms to Widget, which looks similar to a SwiftUI View with a couple of extra options:

You must provide a kind String constant, with a unique (to the app) identifier for the type of widget.
You need to return a WidgetConfiguration object from body, and provide the configurationDisplayName(_) and description(_) view modifiers. The simplest option here is a StaticConfiguration (well, I haven’t learned about any others yet).

struct MyWidget: Widget {
    let kind: String = "MyWidget"

    var body: some WidgetConfiguration {
        StaticConfiguration(kind: kind, provider: MyTimelineProvider()) { entry in
            if #available(iOS 17.0, *) {
                MyWidgetView(entry: entry)
                    .containerBackground(.fill.tertiary, for: .widget)
            } else {
                MyWidgetView(entry: entry)
                    .padding()
                    .background()
            }
        }
        .configurationDisplayName("My Widget")
        .description("This is an example widget.")
        .supportedFamilies([.systemSmall, .systemMedium, .systemLarge])
    }
}

The StaticConfiguration struct takes the widget’s kind string, an instance of your timeline provider, and a closure to call with each entry in the timeline. The closure should return the SwiftUI view configured/rendered for that particular entry.

You can also provide the supportedFamilies view modifier with a list of the different types of widget sizes that this widget supports, including Lock Screen widgets. You can use the environment variable .widgetFamily inside the view to change the layout of the view based on what size widget is currently displayed:

@Environment(\.widgetFamily) var widgetFamily

Apps built using the iOS 17 SDK require all widgets to use the new containerBackground modifier, which automatically handles padding.

Previewing Widgets¶

Widgets are simple to use with SwiftUI previews: you can either preview the widget View by itself, passing a static timeline entry, such as using the pre-Xcode 15 preview provider:

struct MyWidgetView_Previews: PreviewProvider {
    static var previews: some View {
        MyWidgetView(entry: MyWidgetEntry(date: .now, text: "Text"))
            .previewContext(WidgetPreviewContext(family: .systemSmall))
    }
}

Or you can use Xcode 15’s new #Preview macro, with the version specifically designed for widgets, that accepts a timeline of entries. This time you pass it the widget itself, not the view the widget renders:

#Preview(as: .systemSmall) {
    MyWidget()
} timeline: {
    MyWidgetEntry(date: .now, text: "Text 1")
    MyWidgetEntry(date: .now, text: "Text 2")
}

If you’ve reached this far, then you’ve done enough to design the widget and how it populates its timeline into the future, but we still need to tell iOS about it. This is done with one last struct.

To tell iOS about the available widgets in your app, you need a single widget bundle defined in the widget extension, which is a struct conforming to WidgetBundle, and marked with the @main wrapper. Similar to SwiftUI views, this requires one computed parameter, body, but this time is of type some Widget:

@main
struct MyWidgets: WidgetBundle {
    var body: some Widget {
        MyWidget()
    }
}

Multiple different widgets can be returned, just put each on a new line within the body. You can also do some logic here, such as if #available checks to limit certain widgets to particular iOS versions, etc.

If you have multiple widgets that need the same data, you can reuse the same Timeline Entry and Timeline Provider in multiple Widget structs.

With that, your app should be able to provide one or more widgets to the user, and control what sizes they are available in. However, you can’t yet provide options for the user to pick from, allowing them to “edit” the widget. I’ll write up what I know about that in another post, soon!

Review: 43215 The Enchanted Treehouse

2023-06-18T00:00:00+01:00

My latest LEGO review is up on Brickset, of the Disney 100 Enchanted Treehouse.

The star of the set is clearly the impressive selection of minidolls. Their shape definitely suits the Disney Princesses more than a minifigure would; it is just a shame their articulation is significantly less.

The two halves of the treehouse look fantastic together, and there’s plenty of play value with the slide, stairs, zip wire, canoe, and various other smaller builds and interactive sections. It looks good both on display and during play.

Matching the List background colour in SwiftUI

2023-03-26T20:00:00+01:00

I recently came across a situation where I wanted to match the background colour of a a header above a SwiftUI List (using the default .insetGrouped List style) to that used by the List itself. I had done no styling to the List itself, so was relying on the system-provided background colour—this is what I wanted to match.

I tried a couple of the standard constants provided by UIColor, and landed on .secondarySystemBackground. It wasn’t until I had the build running on my phone and I was using the app later in the day that I noticed something was off slightly:

In light mode, everything was fine; but in dark mode, the background of the header and navigation toolbar wasn’t dark enough! It turns out that what I actually wanted was .systemGroupedBackground:

Now they match up as intended. Let this be a lesson to myself to test in both light mode and dark mode when developing anything that relies on colour!

Review: 31138 Beach Camper Van

2023-03-26T14:00:00+01:00

I am just loving the Creator 3-in-1 sets that LEGO are churning out nowadays:

31138 Beach Camper Van is a perfect example of this: an excellent camper van, some lovely little beach huts, an adorable crab—and that’s all just in the primary build! Let’s take a look at the set in detail, including the two alternative models that often make the 3-in-1 sets the success they are.

Review: 31139 Cozy House

2023-03-16T00:00:00+00:00

I love LEGO’s Creator 3-in-1 range, where every set can be built into three different designs. 31139 Cozy House is no exception, with three excellent builds, and a handful of adorable little bugs to boot!

The primary model of the set is the titular Cozy House (or “cosy”, as we’d be more likely to write here in the UK). It’s a fantastic little two-story building with pitched roofs, a delightful garden, and is full of excellent details!

Review: 60359 Dunk Stunt Ramp Challenge

2023-03-07T00:00:00+00:00

The latest batch of LEGO I’ve been provided to review included three City Stuntz sets, a range that I’ve not built or played with before. They come with flywheel-powered bikes and stunt arenas, and are all pretty creative and fun! The first review went up today, for 60359 Dunk Stunt Ramp Challenge:

Despite the theme entering its third year, this was my first experience of the line, and I was quite impressed! The flywheel-powered bike is a lot of fun, and it kept both my children (aged four and six) entertained for some considerable time (once they stopped fighting over whose turn it was).

Review: 71419 Peach's Garden Balloon Ride

2023-02-25T00:00:00+00:00

Princess Peach is back (in LEGO form) with another expansion set to the Super Mario theme. Huw over at Brickset.com asked me to take a look and see how it stacks up.

It is typical LEGO Super Mario fare: bright and colourful, with standard game mechanics, introducing a new character and recycling some old favourites.

Read the full review on Brickset.com.

Implementing a Tip Jar with Swift and SwiftUI

2023-02-17T00:00:00+00:00

Pressured by friends, I recently added a tip jar to Pendulum, the pen pal tracking app I develop with my friend Alex. It’s implemented (like the rest of the app) in pure SwiftUI, and uses the newer StoreKit 2 APIs to communicate with Apple to fetch the IAP information and make purchases. This is a write of how I muddled through the process, from start to finish.

Defining the tip IAPs¶

The first step is to head into App Store Connect and define the IAPs for each of the tips you want to offer. In my case, I knew what I wanted the tips to be called, in ascending order of price, but not exactly what price each would be. That doesn’t matter for now, though. I had the following in mind, amusingly named after fountain pen nib sizes:

Extra Fine Tip
Fine Tip
Medium Tip
Broad Tip
Stub Tip

To create these in App Store Connect, I headed to the In-App Purchases section under Features on the app’s App Store tab. There, I could create each tip using the plus button. The initial form has three fields:

Type: either Consumable or Non-Consumable. I didn’t know what these are, and had to look them up: consumable IAPs are those that can be purchased multiple times by the user (for things such as in-game currency), and non-consumable IAPs can only be purchased once (for features such as unlocking a premium mode of the app). For a tip jar, I wanted the former.
Reference Name: a name for the IAP, solely for your own use. It doesn’t appear anywhere public; for ease, I entered the names I’d chosen for the tips above.
Product ID: a unique identifier for the IAP. I wasn’t sure how unique this was meant to be, so to be on the safe side I went for the usual Apple-style of defining them as reversed-DNS bundle identifiers. For example, uk.co.bencardy.Pendulum.ExtraFineTip, etc.

Once created, to complete the IAP you need to define a few extra fields that aren’t present on the initial form, such as the Price Schedule (where you set the cost of the IAP, using Apple’s price tiers), and the App Store Localization, where you define how the tip appears (its name and description) in the App Store for each language. I defined only “English (U.K.)” which is all the app is offered in.

Defining the tips in Swift¶

StoreKit2 doesn’t have an API to fetch all the IAPs associated with an app; instead, you need to request specific Product IDs known by the app ahead of time. To this end, I decided it would be best to represent the available tips in the app with an enum, based off their unique IDs:

enum TipJar: String, CaseIterable {
    case extraFine = "uk.co.bencardy.Pendulum.ExtraFineTip"
    case fine = "uk.co.bencardy.Pendulum.FineTip"
    case medium = "uk.co.bencardy.Pendulum.MediumTip"
    case broad = "uk.co.bencardy.Pendulum.BroadTip"
    case stub = "uk.co.bencardy.Pendulum.StubTip"

    var name: String {
        switch self {
        case .extraFine:
            return "Extra Fine"
        case .fine:
            return "Fine"
        case .medium:
            return "Medium"
        case .broad:
            return "Broad"
        case .stub:
            return "Stub"
        }
    }
}

I made the enum conform to CaseIterable, meaning I can iterate over TipJar.allCases to display all available tips in the SwiftUI view. This I did inside my TipJarView, wrapping each tip in a button and displaying some placeholder information about each one:

struct TipJarView: View {
    var body: some View {
        List {
            ForEach(TipJar.allCases, id: \.self) { tip in
                Button(action: {}) {
                    HStack {
                        Text(tip.name)
                            .foregroundColor(.primary)
                        Spacer()
                        Text("£??")
                            .foregroundColor(.accentColor)
                    }
                }
            }
        }
        .navigationTitle("Support Pendulum")
    }
}

This presented a list of the available tips, with a place for me to put their prices (once known), and a button to purchase the tip (functionality yet to be completed):

Fetching IAP information with StoreKit 2¶

The next step was to actually fetch the prices I had defined in App Store Connect within the app, and display them. For this, I needed to use Apple’s StoreKit 2 APIs. The particular one I’m interested in here is Product.products(for:), which returns an array of Product objects for each ID passed in. I decided to add a static method to the TipJar enum to call this with all my IAP IDs, and return a mapping of [TipJar: Product] that the view could use. The new StoreKit 2 APIs are all asyncronous, so my function needed to be to:

import StoreKit

extension TipJar {
    static func fetchProducts() async -> [Self: Product] {
        do {
            let products = try await Product.products(for: Self.allCases.map { $0.rawValue })
            var results: [Self: Product] = [:]
            for product in products {
                if let type = TipJar(rawValue: product.id) {
                    results[type] = product
                }
            }
            return results
        } catch {
            storeLogger.error("Could not fetch products: \(error.localizedDescription)")
            return [:]
        }
    }
}

(I am sure there is a more concise way to compile the dictionary, but those are the kinds of Swift tricks I am not yet proficient enough in the language to be able to come up with when I need them, so a simple for loop had to suffice here.)

With this extension in place, I can add a new State variable to my view, and fetch the product information when the view is loaded:

struct TipJarView: View {
    @State private var tipJarPrices: [TipJar: Product] = [:]

    var body: some View {
        List {
            ...
        }
        .task {
            let products = await TipJar.fetchProducts()
            DispatchQueue.main.async {
                withAnimation {
                    self.tipJarPrices = products
                }
            }
        }
    }
}

I can now use this information in the loop around the products. The Product object provides a displayPrice property, which handily returns the price of the tip in the user’s local currency, with the currency symbol:

ForEach(TipJar.allCases, id: \.self) { tip in
    Button(action: {}) {
        HStack {
            Text(tip.name)
                .foregroundColor(.primary)
            Spacer()
            if let product = tipJarPrices[tip] {
                Text(product.displayPrice)
                    .foregroundColor(.accentColor)
            }
        }
    }
}

After a brief moment with no prices available, they suddenly all fade in:

We can do better than that, though. Using another state variable, we can notify the view when the product information has been loaded, and display a progress spinner until that point. We also need to handle the case that, for some reason, the products have been fetched but a particular tip isn’t present. I chose to do so with a simple warning triangle.

struct TipJarView: View {
    @State private var tipJarPrices: [TipJar: Product] = [:]
    @State private var productsFetched: Bool = false

    var body: some View {
        List {
            ForEach(TipJar.allCases, id: \.self) { tip in
                Button(action: {}) {
                    HStack {
                        Text(tip.name)
                            .foregroundColor(.primary)
                        Spacer()
                        if let product = tipJarPrices[tip] {
                            Text(product.displayPrice)
                                .foregroundColor(.accentColor)
                        } else {
                            if productsFetched {
                                Image(systemName: "exclamationmark.triangle")
                            } else {
                                ProgressView()
                            }
                        }
                    }
                }
            }
        }
        .task {
            let products = await TipJar.fetchProducts()
            DispatchQueue.main.async {
                withAnimation {
                    self.tipJarPrices = products
                    self.productsFetched = true
                }
            }
        }
    }
}

Making a purchase¶

To initiate the actual purchase of the IAP, we need to call the Product‘s .purchase() method. This async method returns a result indicating whether the purchase was successful or not, and a few other bits of information. As is my way, I chose to wrap this up in a method on the TipJar enum:

extension TipJar {
    func purchase(_ product: Product) async -> Bool {
        storeLogger.debug("Attempting to purchase \(self.rawValue)")
        do {
            let purchaseResult = try await product.purchase()
            switch purchaseResult {
            case .success(let verificationResult):
                storeLogger.debug("Purchase result: success")
                switch verificationResult {
                case .verified(let transaction):
                    storeLogger.debug("Purchase success result: verified")
                    await transaction.finish()
                    return true
                default:
                    storeLogger.debug("Purchase success result: unverified")
                    return false
                }
            default:
                return false
            }
        } catch {
            storeLogger.error("Could not purchase \(self.rawValue): \(error.localizedDescription)")
            return false
        }
    }
}

For ease of use in the view, I convert the result into a simple true or false for whether the purchase went through successfully. In the view, I can fire this off inside a Task in the button’s action method, and handle the response appropriately. In this case, I want to display an alert saying thank you on a successful purchase, and do nothing if it was cancelled:

struct TipJarView: View {
    ...
    @State private var showingSuccessAlert: Bool = false
    var body: some View {
        List {
            ForEach(TipJar.allCases, id: \.self) { tip in
                Button(action: {
                    storeLogger.debug("\(tip.rawValue) tapped")
                    if let product = tipJarPrices[tip] {
                        Task {
                            if await tip.purchase(product) {
                                DispatchQueue.main.async {
                                    withAnimation {
                                        showingSuccessAlert = successful
                                    }
                                }
                            }
                        }
                    }
                }) {
                    ...
                }
            }
        }
        .alert(isPresented: $showingSuccessAlert) {
            Alert(title: Text("Purchase Successful"), message: Text("Thank you for supporting Pendulum!"), dismissButton: .default(Text("🧡")))
        }
        ...
    }
}

We now have a fully-functional tip jar! Users can view the list of tips, complete with pricing information in their own local currency, and tap on a tip to purchase it.

Preventing user interaction¶

The final niggle I wanted to fix was preventing user interaction with the tip buttons in three situations:

while the tip information is still loading,
if there was an error loading a particular tip, and
while an IAP purchase is in progress.

The first two situations can be handled together: in both cases, the tipJarPrices dict has no entry for the given tip. A simple disabled modifier on the Button will prevent the user from tapping it:

struct TipJarView: View {
    ...
    var body: some View {
        List {
            ForEach(TipJar.allCases, id: \.self) { tip in
                Button(action: { ... }) {
                    ...
                }
                .disabled(tipJarPrices[tip] == nil)
            }
        }
        ...
    }
}

The latter requires us to store some information about whether a purchase is in progress or not. Again, a State variable is perfect here. We can set it when the tip is tapped, and check it later:

struct TipJarView: View {
    ...
    @State private var pendingPurchase: TipJar? = nil
    var body: some View {
        List {
            ForEach(TipJar.allCases, id: \.self) { tip in
                Button(action: {
                    guard pendingPurchase == nil else { return }
                    storeLogger.debug("\(tip.rawValue) tapped")
                    if let product = tipJarPrices[tip] {
                        withAnimation {
                            pendingPurchase = tip
                        }
                        Task {
                            let successful = await tip.purchase(product)
                            storeLogger.debug("Successful? \(successful)")
                            DispatchQueue.main.async {
                                withAnimation {
                                    showingSuccessAlert = successful
                                    pendingPurchase = nil
                                }
                            }
                        }
                    }
                }) {
                    GroupBox {
                        HStack {
                            Text("\(tip.name) Tip")
                                .fullWidth()
                            if let product = tipJarPrices[tip] {
                                if pendingPurchase == tip {
                                    ProgressView()
                                } else {
                                    Text(product.displayPrice)
                                        .foregroundColor(.accentColor)
                                }
                            } else {
                                if productsFetched {
                                    Image(systemName: "exclamationmark.triangle")
                                } else {
                                    ProgressView()
                                }
                            }
                        }
                    }
                    .foregroundColor(.primary)
                }
                .disabled(tipJarPrices[tip] == nil || pendingPurchase != nil)
            }
        }
        ...
    }
}

There’s a few parts to this code, so I’ll highlight them here:

The State variable stores whether or not a purchase is in progress, and if so, which tip is being purchased.
When a tip is tapped, we guard against making multiple concurrent purchases by immediately returning if pendingPurchase isn’t nil.
If there’s no purchase in progress, we update pendingPurchase when a tip is tapped, and set it back to nil once the purchase has completed.
If a purchase is pending for a given tip (purchasePending == tip), we display a progress spinner instead of the price, so the user knows that something is still happening.
Finally, we disable the button for each tip while a purchase is in progress.

What I learned¶

In putting this tip jar together, I learned a number of things, not least:

how to define IAPs in App Store Connect;
how to fetch that IAP information using StoreKit 2, and display it in the app; and
how to initiate IAP purchases when the user taps a button, and handle the various possible responses.

There are a number of ways we could improve upon this basic tip jar, but it’s a pretty decent start. In my own implementation in the app, I also added support for storing a history of how many of each tip the user has purchased, in order to show them the size of their “tip collection” for a little bit of whimsy (and to hopefully encourage more tips!). That’s left as an exercise for the reader; but I’m storing the information in NSUbiquitousKeyValueStore, a useful little class that automatically syncs its using iCloud.

Hopefully you’ve found some useful information in this post to inspire you to add a tip jar to your own indie apps! I’d love to hear about them: let me know on Mastodon.

SwiftUI: Equal Width Icons

2023-02-02T00:00:00+00:00

Following on from my previous post on SwiftUI Text alignment, I thought I’d post about another common issue I run into and how to solve it relatively simply: equal width icons. This logic applies to any series of Views you want to display equally in either height or width, but the most common place it occurs in my own code is when using SF Symbols. Each symbol has its own width, so when using them as bullets or in other situations where you want them to line up it can be infuriating.

Let’s set the stage with some code. The example I’m using is the ubiquitous “What’s New” sheet, found in many of Apple’s own apps. I’ve borrowed the text and icons from the latest update to Penedex, a pen-tracking app developed by Connor Rose. Here’s the sample View:

struct EqualWidthIcons: View {
    var body: some View {
        VStack(spacing: 20) {

            VStack {
                Text("What's New!")
                    .font(.largeTitle)
                    .bold()
                Text("Version 2023.01")
            }
            .padding(.bottom)

            HStack(alignment: .top) {
                Image(systemName: "star.circle.fill")
                    .font(.title)
                    .foregroundColor(.yellow)
                VStack(alignment: .leading) {
                    Text("Star Ratings Toggle")
                        .font(.headline)
                    Text("If you believe all your pens are your favourite, you can now turn off star ratings via Settings.")
                }
                .fullWidth()
            }

            HStack(alignment: .top) {
                Image(systemName: "square.and.arrow.up.fill")
                    .font(.title)
                    .foregroundColor(.green)
                VStack(alignment: .leading) {
                    Text("Share Sheet Fix")
                        .font(.headline)
                    Text("Fixed an issue where the date in your Currently Ink'd shared image would not display correctly.")
                }
                .fullWidth()
            }

            HStack(alignment: .top) {
                Image(systemName: "scroll.fill")
                    .font(.title)
                    .foregroundColor(.blue)
                VStack(alignment: .leading) {
                    Text("Brand List Fix")
                        .font(.headline)
                    Text("Fixed issues with duplicate brands populating your Brand List.")
                }
                .fullWidth()
            }

            HStack(alignment: .top) {
                Image(systemName: "ladybug.fill")
                    .font(.title)
                    .foregroundColor(.red)
                VStack(alignment: .leading) {
                    Text("Misc. Bug Fixes")
                        .font(.headline)
                    Text("Plenty of other minor improvements.")
                }
                .fullWidth()
            }

            Spacer()
        }
        .padding()
    }
}

A series of repeated sections (don’t worry, it’ll be much neater by the end of the post), each with an icon, a title and a short summary. It makes use of the fullWidth() modifier from my previous post. This is how iOS renders it:

As a starter for ten, this is pretty good! But the scroll icon is wider than the previous two, and the ladybird icon even wider still. This pushes the text out to the right and it no longer lines up. We could manually define a width for the icon:

HStack(alignment: .top) {
    Image(systemName: "square.and.arrow.up.fill")
        .font(.title)
        .foregroundColor(.green)
        .frame(width: 50)
    VStack(alignment: .leading) {
        Text("Share Sheet Fix")
            .font(.headline)
        Text("Fixed an issue where the date in your Currently Ink'd shared image would not display correctly.")
    }
    .fullWidth()
}

(From now on, I’m only going to show the code for one of the four sections. The others are identical in all but the content.)

Yay, that works!

But it’s a bit of a “magic number”, and one that would likely need to be tweaked should you change the icons at a later date. Not to mention that it just won’t scale with the icon if the user adjusts the text size on their iOS device. We can do better than that.

There’s three parts to the solution. We need to:

read the width of each icon,
store the maximum of those widths somewhere, and
set the width of each icon to that maximum.

Let’s take these one at a time.

Read the width of each icon¶

This is easily achieved using a GeometryReader. I have a bit of a love/hate relationship with this SwiftUI utility, but in this case it works very well. Appyling it as a background to the icon means it will grow to match the size of the icon’s view, and we can read the frame’s size:

Image(systemName: "square.and.arrow.up.fill")
    .font(.title)
    .foregroundColor(.green)
    .background {
        GeometryReader { geo in
            // geo.size.width is the width of the icon
        }
    }

But what we can do with that value?

Store the maximum width¶

In order to calculate the maximum, we need a couple of things. We need a State variable for the max icon width, and let’s give it a sensible default:

@State private var iconWidth: CGFloat = 20

And we need a way to accumulate the values read by each GeometryReader and take the maximum for our iconWidth variable. SwiftUI provides us with just the thing: a PreferenceKey. This is a strange bit of SwiftUI that allows us to combine a number of values into a single one, and store it somewhere. First, we need to define a custom PreferenceKey, with a reduce function that returns the maximum of the values it is passed. I like to do this on an extension of the main view:

private extension EqualWidthIcons {
    struct IconWidthPreferenceKey: PreferenceKey {
        static let defaultValue: CGFloat = 0
        static func reduce(value: inout CGFloat, nextValue: () -> CGFloat) {
            value = max(value, nextValue())
        }
    }
}

The code here is a little odd, but the important part is the call to max, setting the value variable to the maximum of either what it was before, or the value it has just been passed (the result of the nextValue() call).

Now we need to use this PreferenceKey in our GeometryReader. To do so, we have to call .preference(key:value:) on a View. We can place an invisible view in the GeometryReader and use it there:

Image(systemName: "square.and.arrow.up.fill")
    .font(.title)
    .foregroundColor(.green)
    .background {
        GeometryReader { geo in
            Color.clear.preference(key: EqualWidthIcons.IconWidthPreferenceKey.self, value: geo.size.width)
        }
    }

Applying this to each icon will propagate the maxiumum size up into our EqualWidthIcons.IconWidthPreferenceKey.

Set the width of each icon¶

Now all that’s left is to set the width of each icon to that maximum. Remember the State variable we created for it previously? We can watch for changes to the PreferenceKey and update it accordingly. I like to do this on the highest view in the hierarchy, the immediate one returned by body (in this case, that’s the outer VStack):

var body: some View {
    VStack {
        // Rest of view...
    }
    .onPreferenceChange(EqualWidthIcons.IconWidthPreferenceKey.self) { value in
        self.iconWidth = value
    }
}

Finally, update each icon to use this value as its width. It’s important that we set the frame after the GeometryReader background.

Image(systemName: "square.and.arrow.up.fill")
    .font(.title)
    .foregroundColor(.green)
    .background {
        GeometryReader { geo in
            Color.clear.preference(key: EqualWidthIcons.IconWidthPreferenceKey.self, value: geo.size.width)
        }
    }
    .frame(width: iconWidth)

And voila! Each icon has the same width, and will scale along with dynamic type as specified by the user.

Cleaning up¶

This works great, but we have a fair bit of duplicated code. We did already, but since we’ve added the background, GeometryReader, and frame definitions, the sections have become fairly unwieldy. It’s probably time we split it out into its own view:

struct WhatsNewSection: View {

    let icon: String
    let iconColor: Color
    let title: String
    let summary: String

    var body: some View {
        HStack(alignment: .top) {
            Image(systemName: icon)
                .font(.title)
                .foregroundColor(iconColor)
                .background {
                    GeometryReader { geo in
                        Color.clear.preference(key: EqualWidthIcons.IconWidthPreferenceKey.self, value: geo.size.width)
                    }
                }
//              How do we read the iconWidth here?
//              .frame(width: iconWidth)
            VStack(alignment: .leading) {
                Text(title)
                    .font(.headline)
                Text(summary)
            }
            .fullWidth()
        }
    }

}

This dramatically reduces the size of the original view:

struct EqualWidthIcons: View {

    @State private var iconWidth: CGFloat = 20

    var body: some View {
        VStack(spacing: 20) {

            VStack {
                Text("What's New!")
                    .font(.largeTitle)
                    .bold()
                Text("Version 2023.01")
            }
            .padding(.bottom)

            WhatsNewSection(icon: "star.circle.fill", iconColor: .yellow, title: "Star Ratings Toggle", summary: "If you believe all your pens are your favourite, you can now turn off star ratings via Settings.")
            WhatsNewSection(icon: "square.and.arrow.up.fill", iconColor: .green, title: "Share Sheet Fix", summary: "Fixed an issue where the date in your Currently Ink'd shared image would not display correctly.")
            WhatsNewSection(icon: "scroll.fill", iconColor: .blue, title: "Brand List Fix", summary: "Fixed issues with duplicate brands populating your Brand List.")
            WhatsNewSection(icon: "ladybug.fill", iconColor: .red, title: "Misc. Bug Fixes", summary: "Plenty of other minor improvements.")

            Spacer()

        }
        .padding()
        .onPreferenceChange(EqualWidthIcons.IconWidthPreferenceKey.self) { value in
            self.iconWidth = value
        }
    }
}

But you may have noticed the question in the comments in the WhatsNewSection code: where do we read iconWidth from now?

We have to pass it down as a binding from the parent view:

struct WhatsNewSection: View {
    let icon: String
    let iconColor: Color
    let title: String
    let summary: String
    @Binding var iconWidth: CGFloat
    // Rest of view...

Read it as usual to set the icon’s frame:

Image(systemName: icon)
    .font(.title)
    .foregroundColor(iconColor)
    .background {
        GeometryReader { geo in
            Color.clear.preference(key: EqualWidthIcons.IconWidthPreferenceKey.self, value: geo.size.width)
        }
    }
    .frame(width: iconWidth)

And finally, pass the binding through from the main view:

WhatsNewSection(icon: "star.circle.fill", iconColor: .yellow, title: "Star Ratings Toggle", summary: "If you believe all your pens are your favourite, you can now turn off star ratings via Settings.", iconWidth: $iconWidth)

A better alternative¶

For this particular situation, we can actually do away with the PreferenceKey entirely, if we switch our layout to using a Grid. Grids automatically size the width of their columns based on the widest cell within the column, which is exactly what we want. Here’s a verison of the code using Grid instead:

struct WhatsNewGridRow: View {
    let icon: String
    let iconColor: Color
    let title: String
    let summary: String

    var body: some View {
        GridRow(alignment: .top) {
            Image(systemName: icon)
                .font(.title)
                .foregroundColor(iconColor)
            VStack(alignment: .leading) {
                Text(title)
                    .font(.headline)
                Text(summary)
            }
            .fullWidth()
        }
    }

}

struct GridWidthIcons: View {
    var body: some View {
        VStack(spacing: 20) {
            VStack {
                Text("What's New!")
                    .font(.largeTitle)
                    .bold()
                Text("Version 2023.01")
            }
            .padding(.bottom)

            Grid(horizontalSpacing: 10, verticalSpacing: 10) {
                WhatsNewGridRow(icon: "star.circle.fill", iconColor: .yellow, title: "Star Ratings Toggle", summary: "If you believe all your pens are your favourite, you can now turn off star ratings via Settings.")
                WhatsNewGridRow(icon: "square.and.arrow.up.fill", iconColor: .green, title: "Share Sheet Fix", summary: "Fixed an issue where the date in your Currently Ink'd shared image would not display correctly.")
                WhatsNewGridRow(icon: "scroll.fill", iconColor: .blue, title: "Brand List Fix", summary: "Fixed issues with duplicate brands populating your Brand List.")
                WhatsNewGridRow(icon: "ladybug.fill", iconColor: .red, title: "Misc. Bug Fixes", summary: "Plenty of other minor improvements.")
            }

            Spacer()
        }
        .padding()
    }
}

The result is identical, with a little less code a lot less complexity. However, there are still some situations where you want icons or other views to match widths or heights but a grid isn’t appropriate—there may be other content between the views, for example, that you don’t want conforming to a grid—so the PreferenceKey method is still valuable to know.

The full code for both solutions can be found on Github.

SwiftUI Text Views and Alignment

2023-01-25T00:00:00+00:00

There’s no doubting that SwiftUI makes app development fast and easy—I certainly wouldn’t have two apps on the store by now without it—but it’s not without its sharp edges and unexpected behaviours.

One of these that I ran into pretty early on is how Text views behave, particularly with regard to alignment and how it lays itself out when text spills over more than one line.

Simple `Text` views¶

Putting a bare Text view on the screen, and it’ll be centered by default:

Text("Hello, World!")

Putting a border around the Text view shows us what the boundaries of the view’s frame are, and they hug the text as tightly as possible. The Text‘s frame doesn’t expand to fill all the available space; only what is necessary.

Text("Hello, World!")
    .border(.red)

If the text flows onto multiple lines, it will be left-aligned, and expand to fill the width available before wrapping the text:

Text("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.")
    .border(.red)

In this particular case, the frame has expanded to fill the entire width of the screen—but this is only because the second line happens to fit exactly. The frame still wants to be centered, as you can see by adjusting the paragraph slightly:

Text("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do abore et dolore magna aliqua.")
    .border(.red)

This is often not the behaviour we want from our views! If we had multiple paragraphs, or different sections as part of a stack, they wouldn’t necessarily be aligned with each other, and it’s entirely dependent on exactly what words are in each and where the line breaks fall.

VStack(spacing: 10) {
    Text("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do abore et dolore magna aliqua.")
    Text("Lorem ipsum dolor sit amet, sed do abore dolore magna aliqua.")
}
.padding()

With the borders on, you can clearly see what’s going on:

VStack(spacing: 10) {
    Text("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do abore et dolore magna aliqua.")
        .border(.red)
    Text("Lorem ipsum dolor sit amet, sed do abore dolore magna aliqua.")
        .border(.green)
}
.padding()

A real world example¶

Let’s use a less contrived example: a settings page, with multiple different settings each with explanatory text. For lack of imagination, I’ve borrowed the settings and text from _DavidSmith‘s Pedometer++ app (inspired by a recent post in his excellent Design Notes Diary series).

VStack(spacing: 10) {
    GroupBox {
        HStack {
            Text("Allow Rest Days")
                .font(.headline)
            Spacer()
        }
        Text("When enabled, activity streaks will not be broken by a single day missed after six consecutive days of reaching your goal.")
        Picker("Allow Rest Days", selection: $allowRestDays) {
            Text("Rest Days").tag(true)
            Text("Unbroken Streaks").tag(false)
        }
        .pickerStyle(.segmented)
    }
    GroupBox {
        HStack {
            Text("Wheelchair Mode")
                .font(.headline)
            Spacer()
        }
        Text("Have Pedometer++ use your Apple Watch to measure your daily wheelchair push counts rather than steps.")
        Picker("Wheelchair Mode", selection: $allowRestDays) {
            Text("Steps").tag(false)
            Text("Pushes").tag(true)
        }
        .pickerStyle(.segmented)
    }
}
.padding()

In order to left-align the settings headers, I’ve wrapped them in an HStack and followed them by a Spacer. There is a better way that we’ll come to later, but for now you can clearly see that the two explanatory paragraphs don’t align with each other, or with their surrounding content!

Adding borders in, it’s obvious why:

Fixing the alignment problems¶

We could fix this in the same way that we pushed the titles to the left - but a better way would be to use the frame modifier on the Text views to tell them to expand to take all available space horizontally, rather than just what they require. This is a technique we can also use on the headings.

We can do this by using .frame(minWidth: 0, maxWidth: .infinity, alignment: .leading), telling SwiftUI that we want the frame to fill the entire width of its container, and align the text inside it to the left. In the code below, I’ve added it to four places: the two headers, and the two paragraphs.

VStack(spacing: 10) {
    GroupBox {
        Text("Allow Rest Days")
            .font(.headline)
            .frame(minWidth: 0, maxWidth: .infinity, alignment: .leading)
        Text("When enabled, activity streaks will not be broken by a single day missed after six consecutive days of reaching your goal.")
            .frame(minWidth: 0, maxWidth: .infinity, alignment: .leading)
        Picker("Allow Rest Days", selection: $allowRestDays) {
            Text("Rest Days").tag(true)
            Text("Unbroken Streaks").tag(false)
        }
        .pickerStyle(.segmented)
    }
    GroupBox {
        Text("Wheelchair Mode")
            .font(.headline)
            .frame(minWidth: 0, maxWidth: .infinity, alignment: .leading)
        Text("Have Pedometer++ use your Apple Watch to measure your daily wheelchair push counts rather than steps.")
            .frame(minWidth: 0, maxWidth: .infinity, alignment: .leading)
        Picker("Wheelchair Mode", selection: $allowRestDays) {
            Text("Steps").tag(false)
            Text("Pushes").tag(true)
        }
        .pickerStyle(.segmented)
    }
}
.padding()

Once again, putting the borders back in, it’s clear what’s now going on:

A brief note about the way alignment: works within the frame modifier: it is not for aligning the text, it is for aligning the view within the frame. When we say .frame(minWidth: 0, maxWidth: .infinity, alignment: .leading), despite what it looks like, we’re not actually asking SwiftUI to change the size of the Text view—instead, we’re asking SwiftUI to place that view within a frame that takes up the specified space, and place it at the left of the space. If we put a border around the Text view before the frame modifier (green), and another after (red), we can see what SwiftUI is doing under the hood:

Text("Allow Rest Days")
    .font(.headline)
    .border(.green)
    .frame(minWidth: 0, maxWidth: .infinity, alignment: .leading)
    .border(.red)
Text("When enabled, activity streaks will not be broken by a single day missed after six consecutive days of reaching your goal.")
    .border(.green)
    .frame(minWidth: 0, maxWidth: .infinity, alignment: .leading)
    .border(.red)

A neat solution¶

In fact, this is such a common thing I want to do to Text views within my apps, that I’ve written a small view modifier to handle it. Typing .frame(minWidth: 0, maxWidth: .infinity, alignment: .leading) in so many places is a pain in the backside.

struct FullWidthText: ViewModifier {

    var alignment: TextAlignment = .leading

    var frameAlignment: Alignment {
        switch alignment {
        case .leading:
            return .leading
        case .trailing:
            return .trailing
        case .center:
            return .center
        }
    }

    func body(content: Content) -> some View {
        content
            .multilineTextAlignment(alignment)
            .frame(minWidth: 0, maxWidth: .infinity, alignment: frameAlignment)
    }
}

extension View {
    func fullWidth(alignment: TextAlignment = .leading) -> some View {
        modifier(FullWidthText(alignment: alignment))
    }
}

Now we can clean up our previous code, producing the same result but with a much neater and easier to remember view modifier:

VStack(spacing: 10) {
    GroupBox {
        Text("Allow Rest Days")
            .font(.headline)
            .fullWidth()
        Text("When enabled, activity streaks will not be broken by a single day missed after six consecutive days of reaching your goal.")
            .fullWidth()
        Picker("Allow Rest Days", selection: $allowRestDays) {
            Text("Rest Days").tag(true)
            Text("Unbroken Streaks").tag(false)
        }
        .pickerStyle(.segmented)
    }
    GroupBox {
        Text("Wheelchair Mode")
            .font(.headline)
            .fullWidth()
        Text("Have Pedometer++ use your Apple Watch to measure your daily wheelchair push counts rather than steps.")
            .fullWidth()
        Picker("Wheelchair Mode", selection: $wheelchairMode) {
            Text("Steps").tag(false)
            Text("Pushes").tag(true)
        }
        .pickerStyle(.segmented)
    }
}
.padding()

As you may have noticed, it also supports providing the other TextAlignment options for multiline text, passed to the .fullWidth(alignment:) videw modifier: .leading (the default), .centered, and .trailing.

Hopefully this can be of some use to you and help clear up some of the oddities surrounding the layout of text in SwiftUI! If you do find it helpful, I’d love for you to let me know.

Diamine Inkvent 2022

2023-01-21T00:00:00+00:00

The Diamine Inkvent advent calendars are something I never imagined existed—24 small 12ml bottles of unique ink, and one 30ml bottle on Christmas Day. 2022 was the second year they produced one, and although I didn’t buy one for advent itself, I did pick one up at half price a couple of days after Christmas from Cult Pens.

The little 12ml bottles are adorably cute, and all the inks are somewhat Christmas- or winter-themed in name. I opened the calendar all in one go, and spent half an hour one afternoon swatching every ink. I can recommend a dip pen if you’re going to do this—I used a Lamy Safari, dipping the nib into each bottle in turn, but thanks to the feed it was a bit more of a pain to clean between inks than a proper dip pen would have been.

I swabbed three to a swatch for my homemade col-o-ring, and gave the large 30ml bottle its own. These are cards I’ve cut from 350gsm watercolour postcards, rounded the corners using a corner punch, and punched a hole in to thread them through a keyring. The result is a fantastic way to flick through my available inks and make a choice, and I love having it as something to play with sitting on my desk:

Speaking of which, how beautiful is that Van Diemen’s Azure Kingfisher from the Wilderness Series? It has such a beautiful golden shimmer and a slight red sheen. It was a birthday gift from a couple of wonderful friends, along with a custom pen from Just Turnings that matches it perfectly, and shows off its properties fantastically with a broad nib.

I’m not sure I’m likely to buy the advent calendar full price next Christmas—it is a fair amount of money, and I have many inks I still haven’t used yet from it—but I think they’re a fantastic idea from Diamine. Judging by last year, they’ll be selling each of the colours individually later in the year in larger bottles, so if there’s any that really take my fancy I don’t need to worry about 12ml not going particularly far.

So far, my favourite is Flame, but I am particularly partial to a good orange. What’s yours?

Swift Charts & Calendar Weekdays

2023-01-20T16:30:00+00:00

I’ve recently been working on adding a statistics section to Pendulum, the pen pal tracking app I develop with my friend Alex. This seemed like the perfect opportunity to use Swift Charts, Apple’s new charting framework.

I ultimately wanted to end up with a graph like the following:

Swift Charts can perfectly handle multiple datasets on one graph, but the problem I ran into was that it doesn’t seem to have a way to natively aggregate data per day of the week. If I only had seven days worth of data, it would be fine—I could display just the day name on the axis, and no days would be repeated because I wouldn’t be displaying more than a week of data. However, as I want to aggregate every event, this wasn’t going to work. I decided to do the grouping of the data myself, and just pass Swift Charts a pre-binned dataset for it to present, where it wouldn’t have to worry about dates at all.

I had one other problem I wanted to solve: I wanted the graph to start on whatever the current locale thinks the start of the week is¹. For us in the UK and Europe, we generally consider Monday the beginning of the week, as reflected in the graph above. But for the US, it should probably start with Sunday.

In order to generate the seven “bins” for the chart to show, I could use the handy Calendar.current.shortWeekdaySymbols property, which produces an array of the shortened names of the week, properly localised to the user’s current locale. However, regardless of locale, this array always starts with Sunday and ends with Saturday. There’s another property of the calendar, .firstWeekday, that returns a number between 1 (for Sunday) and 7 (for Saturday) representing what the locale considers to be the first day of the week. Using this, I can shift the array from shortWeekdaySymbols to produce the output in the right order. I decided to wrap both these pieces of information up in an enum to represent each day of the week:

enum Weekday: Int, CaseIterable {
    case sun = 1
    case mon = 2
    case tue = 3
    case wed = 4
    case thu = 5
    case fri = 6
    case sat = 7

    var shortName: String {
        return Calendar.current.shortWeekdaySymbols[self.rawValue - 1]
    }

    static var orderedCases: [Weekday] {
        Self.allCases.shiftRight(by: Calendar.current.firstWeekday - 1)
    }
}

You’ll also notice I’m using an extension to Array that allows me to shift an array, wrapping the values around to the end as they get popped off the front:

extension Array {
    func shiftRight(by: Int = 1) -> [Element] {
        guard count > 0 else { return self }
        var amount = by
        assert(-count...count ~= amount, "Shift amount out of bounds")
        if amount < 0 { amount += count }
        return Array(self[amount ..< count] + self[0 ..< amount])
    }
}

Now that I have an enum I can use to represent the days of the week correctly, and order them as defined by the user’s locale, I needed to use this somehow to generate data to pass to the chart. I started off by defining a struct to hold a single datapoint:

struct StatusCountByDay: Identifiable {
    let status: EventType
    let day: Weekday
    let count: Int
    var id: String { "\(day)-\(status.rawValue)" }
}

Here, EventType is an internal enum used by Pendulum to mark whether the event was a letter being sent, written, received, etc. What makes each data point unique in the chart is the combination of the day of the week, and the event type, so I combine those two together as the id for the struct.

Next, I needed to fetch the data and group it into buckets:

var days: [Weekday: [Event]] = [:]

for event in Event.fetch(withStatus: [.written, .sent]) {
    if !days.keys.contains(event.wrappedDate.weekday) {
        days[event.wrappedDate.weekday] = []
     }
     days[event.wrappedDate.weekday]?.append(event)
}

I start by defining a dictionary mapping weekdays to an array of events, and then looping over the events I’m interested in and adding them to the corresponding weekday key in the dictionary. This necessitated another extension to a Foundation object, this time on Date²:

extension Date {
    var dayNumberOfWeek: Int? {
        return Calendar.current.dateComponents([.weekday], from: self).weekday
    }
    var weekday: Weekday {
        return Weekday(rawValue: dayNumberOfWeek ?? 0) ?? .sun
    }
}

This uses the .weekday date component from the user’s current calendar, which returns the same 1–7 index as used by .firstWeekday, and returns the corresponding Weekday object.

With the data correctly bucketed, it was time to sum up the series and create the datapoints for the chart. When the data provided is not sequential (such as a series of dates) but is instead discrete (such as list of names, for example) Swift Charts will draw the bars in the order in which it first encounters them. You may think that weekdays are sequential—and you’d be right—but in this case, they’re not an object that Swift Charts understands in that way. So to draw the chart as intended, we need to create a StatusCountByDay instance for each weekday in the order we want. We also need to include one even when the count for that day is zero, because we don’t want the chart to just skip a day. I do this by looping over the weekdays ordered according to the locale, inside that looping over each event type, and calculating the sum for each:

var results: [StatusCountByDay] = []
for eventType in [EventType.written, EventType.sent] {
    for day in Weekday.orderedCases {
        let count = (days[day] ?? []).filter { $0.type == eventType }.count
        results.append(StatusCountByDay(status: eventType, day: day, count: count))
    }
}

Ultimately, we end up with a series of data like the following:

[
    StatusCountByDay(status: .sent, day: .sun, count: 2),
    StatusCountByDay(status: .sent, day: .mon, count: 0),
    StatusCountByDay(status: .sent, day: .tue, count: 1),
    StatusCountByDay(status: .sent, day: .wed, count: 5),
    StatusCountByDay(status: .sent, day: .thu, count: 12),
    StatusCountByDay(status: .sent, day: .fri, count: 5),
    StatusCountByDay(status: .sent, day: .sat, count: 1),
    StatusCountByDay(status: .written, day: .sun, count: 3),
    StatusCountByDay(status: .written, day: .mon, count: 2),
    StatusCountByDay(status: .written, day: .tue, count: 2),
    StatusCountByDay(status: .written, day: .wed, count: 1),
    StatusCountByDay(status: .written, day: .thu, count: 2),
    StatusCountByDay(status: .written, day: .fri, count: 1),
    StatusCountByDay(status: .written, day: .sat, count: 10)
]

All that’s left is to pass that to Swift Charts, for which I’ll break down each section after I show the code:

Chart(results) { data in
    BarMark(
        x: .value("Day", data.day.shortName),
        y: .value("Count", data.count)
    )
    .annotation(position: .top, alignment: .top) {
        if data.count != 0 {
            Text("\(data.count)")
                .font(.footnote)
                .bold()
                .foregroundColor(data.status.color)
                .opacity(0.5)
        }
    }
    .foregroundStyle(by: .value("event", data.status.actionableTextShort))
    .position(by: .value("event", data.status.actionableTextShort))
}
.chartForegroundStyleScale([
    EventType.sent.actionableTextShort: EventType.sent.color,
    EventType.written.actionableTextShort: EventType.written.color,
])

Firstly, we want a bar chart, so the correct type of mark to use is a BarMark. The x axis is the short name of the weekday (“Mon”, “Tue”, etc), and the y axis is the count.

The .annotation section puts the little figures above each bar, and isn’t particularly necessary but I liked the way it looked.

The two BarMark modifiers .foregroundStyle(by:) and .position(by:) both tell Swift Charts how to define and handle each series independently; otherwise, they’d be a single bar, stacked on top of each other within each day. Grouping them by event type, the first modifier tells them to be different colours, and the second puts them as independent bars side by side instead of on top of each other. I use data.status.actionableTextShort as the value to distinguish the data by, because that is what I want shown in the legend beneath the chart (“Sent” vs “Written”, etc).

You can see below the results of the chart without the .position(by:) modifier, and without the .foregroundStyle(by:) modifier, respectively.

Finally, the .chartForegroundStyleScale modifier defines the colours to be used for each series, which is a dictionary mapping the name of the series to its colour. In this case, I use want them using the colour defined for the event type, to keep it consistent with the rest of the app.

I’m quite impressed with Swift Charts and how easy it makes drawing a good looking chart, but there are definitely some things that could be more obvious about it. The lack of decent documentation with plenty of examples and screenshots being a very clear area for improvement!

Yes, I realise none of the rest of the app is localised. Baby steps, though! ↩
As you may have realised by now, I’m quite a fan of writing extensions to standard types for common functions that could end up being performed regularly. They make the rest of the code a lot cleaner. It’s one of my favourite features of Swift. ↩

Review: LEGO Monster Jam Trucks

2023-01-20T00:00:00+00:00

Recently, two more reviews of mine went up on Brickset: one for 42149 Monster Jam Dragon and the other for its counterpart, 42150 Monster Jam Monster Mutt Dalmation. They’re part of a small series that LEGO has released over the past few years, with two pull-back-and-go Technic monster trucks from the Monster Jam sport. Spoilers for the reviews, but I think they’re great little “intro to Technic” sets, and you can’t go wrong at less than £18.

Review: 40651 Australia Postcard

2023-01-03T00:00:00+00:00

I’ve quite liked the previous sets in the LEGO Postcard series, so it was good to get a chance to review the latest, 40651 Australia, even if it’s a slight departure from the rest:

The designers have chosen to represent the entirety of Australia with a small shack, a windpump, an outdoor toilet, a large tree with a cockatoo, and a sign warning of kangaroos. There’s also a Qantas plane flying through the bright blue sky, and small colourful plants growing around the ground.

Brickset LEGO Gift Guide - $50 and up

2022-11-23T00:00:00+00:00

The last two holiday gift guides have been published at Brickset, where we’ve chosen a number of sets in a variety of price brackets. Go and check out the sets between $50 to $100, $100 to $200, and $200 and up!

Brickset LEGO Gift Guide

2022-11-20T00:00:00+00:00

Brickset have started publishing their annual Gift Guide, and this year Huw asked for my thoughts to be included. So far, guides for the first two price ranges have been released, for sets under $25 and sets priced between $25 and $50. Click through to see my recommendations!

Review: 71409 Big Spike's Cloudtop Challenge

2022-10-28T00:00:00+01:00

The last of this round of Super Mario LEGO sets to review, 71409 Big Spike’s Cloudtop Challenge:

LEGO keep on producing Super Mario expansion sets to add to what is clearly a popular theme for them—this year they have released 14 distinct sets in the range so far. 71409 Big Spike’s Cloudtop Challenge is one of the largest, with 540 parts, and packs a decent punch: three opponents, two of which are new, and some fun takes on the interactivity and game play we’ve come to expect with these sets.

LEGO IDEAS Review Results

2022-10-27T00:00:00+01:00

LEGO have announced the results of the latest IDEAS review (the mechanism by which fan-designed models can get made into real LEGO sets, should they reach 10,000 votes and pass the review). Four projects were accepted this time, and I particularly like the look of the Space Age designs, which will hopefully be an instant buy when it eventually comes out some time in 2023/2024. The other three ideas also look fantastic, and it will be interesting to see how LEGO adapts them to become production-ready sets. I hope they include Chris McVeigh on the team designing the Polaroid, as that is right up his alley!

Tales of the Space Age by John Carter ¶

LEGO Insects by hachiroku24 ¶

Polaroid OneStep SX-70 by Minibrick Productions ¶

The Orient Express, a Legendary Train by LEt.sGO ¶

Darker Sublime Text Plugin

2022-10-26T00:00:00+01:00

Black is a popular code formatter for Python code, known for its opinionated uncompromising stance. It’s incredibly helpful for teams working on common Python code to write in the same style, and Black makes that easy, without having to maintain a common set of configuration options between the team members. After all, there aren’t any.

However, adding it to an existing codebase is difficult. It wants to reformat every source file, which can be a pain with version history by creating commits that are purely formatting changes, or adding misleading diffs to commits that are intended for something else. To help overcome this, Darker was created, which runs Black but only on the parts of code that have changed since the last commit. This is perfect for running as a post-save hook in your IDE, to consistently keep your code up to style without altering the parts of the source you haven’t changed.

The Darker documentation includes instructions on how to integrate the formatter with PyCharm, IntelliJ IDEA, Visual Studio Code, Vim, and Emacs—but I use Sublime Text. All it took was to write a simple Sublime Plugin, however, and we’re off to the races:

import sublime_plugin
import os
import subprocess


class DarkerOnSave(sublime_plugin.EventListener):
    def on_post_save_async(self, view):
        filename = view.file_name()
        if view.match_selector(0, "source.python"):
            subprocess.call(["darker", filename], cwd=os.path.dirname(filename))

To add this yourself, go to Tools > Developer > New Plugin… from the menubar, and replace the contents of the file with the above. Save the file as something like darker-on-save.py in the same location it was created in (the default in the save dialog box), and now every time you hit Save on a Python file, it’ll ensure that the code you added or altered is up to scratch with your style guide. Simple!

Useful Avrae Aliases

2022-10-10T00:00:00+01:00

Avrae is a Discord bot that makes running and playing D&D play-by-post games much easier—it provides useful tools such as integration with D&D Beyond, powerful dice-rolling options, and combat initiative tracking.

However, there are some things it doesn’t do well natively. For this, it provides a powerful scripting API via aliases and snippets for you to extend its functionality with your own commands. Many people have written their own, and these are a few of the custom commands that we have set up in our games to make life just a little bit easier.

To use any of these aliases, paste the text in the code blocks below into a DM with Avrae (or any channel they are a member of).

Quick Character Switcher¶

When you link a character from D&D Beyond, Avrae will remember it and allow you to use the character in combat and for ability checks, etc. However, if you’re playing in multiple games, you have to constantly remember to change the active character to the correct one before continuing. We found a handy alias on the Avrae Developer’s Discord for assigning characters to channels, so instead of remembering that “in this channel, I’m Kaith, but in this channel, I’m Elmer”, you can just run !ch to switch to the right character for that game. I’m reproducing that here (tweaked for a recent Avrae update that deprecated a couple of the commands):

!alias ch {{c,id,a,m,n,h,H,w,R=load_json(chars) if exists('chars') else {}, {'c':str(ctx.channel.id),'s':str(ctx.guild.id if ctx.guild else "")} ,&ARGS&[1:],&ARGS&[:1] or 0,'\n','- This Channel','- This Server' ,'',"%x"%roll('1d16777216')}}{{m=(1 if m[0] in 'add'  else 2 if m[0] in 'delete'  else 3 if m[0] in 'roster' else 4 if m[0] in 'help?' else 0) if m else 0}}{{x=not m or ((a[1] if a[1].isdigit() else id.c if a[1] in 'chan' else id.s) if a and len(a)>1 else id.s)}}{{X=not m or ((a[0] if a[0].isdigit() else id.c if a[0] in 'chan' else id.s) if a else id.s)}}{{name=c.get(X)}}{{emb=f' -title "Quick Character Changer" -footer "!ch [help|?] - Bring up the help window" -color {R} '}}{{A=''.join([c[i] for i in c if i==id.c][:1]) or ''.join([c[i] for i in c if i==id.s][:1])}}{{add=not m==1 or not  a or c.update({x:a[0]}) or set_uvar('chars',dump_json(c)) or a[0]}}{{delete=not m==2 or not c.pop(X) or not set_uvar('chars', dump_json(c)) or X}}{{"embed "+emb+(f'-t 10 -desc "Added `{add}` to ID `{x}`."' if (m==1 and a) else f'-t 10 -desc "{"No char found for ID" if not name else f"Removed `{name}` with ID"} `{X}`."' if m==2 else f'-t 20 -f "Roster| {n+(n.join([f"`{i}` - `{c[i]} ` {h if i in id.c else H if id.s and i in id.s else w} " for i in c]) or "*None*")}"' if m==3 else f'-f "!ch|Changes to the appropriate character for the channel/server." -f "!ch roster|View a list of all channel/server id\'s and the character they will load" -f "!ch add <name> [chan⏐id]|Adds `name` to the selected id. Default is server id, `chan` selects the channel id, or you can input the channel/server id manually" -f "!ch delete [chan⏐id]|Deletes the given id. Default is server id, `chan` selects the channel id, or you can input the channel/server id manually" -f "Current ID\'s|`Channel` - `{id.c}`{n}`Server` - `{id.s}`"') if m else (f"char {A}" if A else "embed -t 5 -desc 'Channel not found in list'"+emb)}}

With that alias set, you can run !ch add [character] chan to assign the provided character to the current channel. Now, when you switch channels, you just have to run !ch to activate the right one.

However, remembering to run !ch is easier said than done. How many times have I switched to a channel and run !g lr to give my character a long rest, before realising that I hadn’t switched and had just given one of my other characters a poorly-timed rest instead? To solve this, we put together an alias (worked out mostly by my friend Madi) designed to prefix any command you may want to run, that automatically switches before executing the actual command you asked for:

!alias x multiline
<drac2>
id={'c':str(ctx.channel.id),'s':str(ctx.guild.id if ctx.guild else "")}
c = load_json(chars) if exists('chars') else {}
n ='\n'
A= ''.join([c[i] for i in c if i==id.c][:1]) or ''.join([c[i] for i in c if i==id.s][:1])
return f'!char {A}'
</drac2>
!&*&

For me it’s aliased to x, just to make it quick and easy to type. !x check str will always do a strength check for the right character for the game in this channel. !x g lr will always give the correct character a long rest. In combination with the !ch alias, this is probably the most handy alias I have set up—I only have to remember to always use !x instead of !, and it always just does the right thing.

Feat Spells¶

The other problem we frequently run into is using spells provided by feats. There are many feats that provide the with character additional spells; one’s they’re able to cast a particular number of times between rest, without using up spell slots. A good example is the Magic Initiate feat:

Choose a class: bard, cleric, druid, sorcerer, warlock, or wizard. You learn two cantrips of your choice from that class’s spell list.

In addition, choose one 1st-level spell from that same list. You learn that spell and can cast it at its lowest level. Once you cast it, you must finish a long rest before you can cast it again using this feat.

Avrae only partially understands these. Pulling from D&D Beyond, it creates a custom counter for each spell you’ve learned, with the correct number of “bubbles” for the amount of times you can use it, such as the example in the screenshot below:

Here, Scrat (my Hadozee character) has the Magic Initiate (Cleric): Command counter, that corresponds to his background feat providing that 1-st level spell. Avrae’s also added the spell to Scrat’s spellbook (!sb), meaning Scrat is able to cast it. However, they’re not linked together in any way. Casting the spell uses a spell slot (it shouldn’t) and doesn’t update the counter (it should). This means that instead, there are a number of things I need to remember to do when casting the spell:

Firstly, check the custom counter to see if it’s been used or not (i.e. is the spell available to me, or do I need a long rest first).
Cast the spell without using a spell slot (the -i flag to !cast or !i cast will do this).
Decrement the counter.

To solve this, I wrote a short alias I call !featcast, which can be used in place of !cast (or !i cast) to handle the above three things:

!alias featcast {{a=&ARGS&}}{{H=not a or "help" in a or "?" in a}}{{s,r=H or a[0],H or " ".join(a[1:])}}multiline
<drac2>
if not H:
    ch=character()
    s=s.lower()
    ccs=[x for x in ch.consumables if ":" in x.name and (x.name.split(":")[1].lower().endswith(s.lower()) or x.name.split(": ")[1].lower().startswith(s.lower()))]
    cc=ccs[0] if ccs else None
    if cc:
        t,n=[x.strip() for x in cc.name.split(":")]
        if cc.value > 0:
            i=""
            if combat():
                i="i "
            cc.set(cc.value-1)
            return f"!{i}cast '{n}' -i {r}"
        else:
            return f"!embed -title 'Cannot cast {n}!' -desc '{ch.name} does not have any uses of {n} from the {t} feat available.\n\n**{cc.name}**\n{cc}'"
    else:
        return f"!embed -title 'Could not find a \"{s}\" custom counter' -desc 'Check that your feats for **{ch.name}** are set up correctly.' -thumb <image>"
else:
    return f"!embed -title 'Help for feat-casting' -desc 'Use `!featcast <spell>` to cast a spell provided by a feat, instead of using your spell slots.'"
</drac2>

It relies on the fact that Avrae names the custom counters sensibly, in the format of “Feat Name: Spell Name”. When typing !featcast command -t Target1 -t Target2, it will look for a custom counter named in that way that could possibly match the provided spell name. When it finds one, it checks for a free slot, and casts the spell (with the provided arguments), decrementing the counter.

There are many feats and backgrounds that provide spells, and this alias has made handling them much easier. Hopefully it can be of some use in your games too!

Review: 71406 Yoshi's Gift House

2022-10-07T00:00:00+01:00

I was given a few more of the LEGO Super Mario sets to review for Brickset, including 71407 Yoshi’s Gift House:

Since I was a child, Yoshi has always been my favourite Super Mario character. I couldn’t put my finger on why, but there’s something very whimsical and fun about the dinosaur-like cartoon creature that’s willing to carry Mario around on his back and help out wherever he can.

He’s an iconic part of Mario lore, and has fittingly appeared in a number of sets so far in the Super Mario line. 71406 Yoshi’s Gift House is the latest to feature the character, and is the largest with him as the sole protagonist.

The Lost Jungles of Rabbad: Part 2

2022-10-06T00:00:00+01:00

This is part two in my ongoing series to summarise the Lost Jungles of Rabbad D&D adventure I am taking part in. I previously wrote up the first part, so I highly recommend reading that before continuing here, if you haven’t already!

When we last left our fearless heroes, they had just defeated Dawn Song; on some level, at least—she had turned into a necrodragon, and flown off. Well, Deimos and Qhell weren’t content to leave it at that, and chased after her but were unable to catch up. After licking their wounds, the group turned to examine the items she’d left behind. They found:

the Helm of Earth, made of a simple dark brown wood;
the Staff of Sight, golden, smooth and well-made;
five diamonds; and
an amulet made of a small animal skull dyed blood red.

The Helm and Staff, together with Sumunar’s Hammer, seem to make up the three of the four items that bind Fulgrin in his tomb. Kosta takes the helm, Elmer takes the staff.

Kosta’s Absence Explained¶

Kosta disappeared down the mine, and was taken by Pelor to another plane. There, they meet with The Celestial, the patron with which Kosta did a deal previously. The gods appear to be fighting over him and his allegiance, with Pelor attempting to release Kosta from the binding deal he had unwittingly made with Mr C. They come to an arrangement: Mr C shall only demand four more tasks of Kosta, and Pelor will give him “the amulet”.

Kosta is taken to his old city of Fallen Oak, where he is watching the town under attack, two armies clashing. He watches Father Thason, his adopted father, struck down and killed. Kosta is told he has a choice to make: save Father Thason, or save the city from plunder, pillage, and murder. It is not clear whether the attack is happening in real time, the past, or the future, or even real. Kosta chooses the city, to the Celestial’s anger.

Back at the plane with Pelor, as one of his tasks Kosta is made to pick up a rapier by the Celestial that shocks him with a blast of energy and ages him a few decades. For the final task, the Celestial takes Kosta’s right eye, replacing it with a pulsing purple orb, and disappears.

Pelor then opens the heavens, looking down on the battle between the group and Dawn Song below. With a cry, Kosta jumps, and the portal closes behind him.

Qhell’s Backstory¶

Qhell explains that he has met Dawn Song before:

Several years ago I was taken as a slave, captured by some gang of outlaws. I was a curiosity, sold repeatedly, until I ended up on a ship. I didn’t know where I was or what they intended to do with me, except for that cat. She would come down to the hold every single day to leer at her cargo, torturing one lucky creature each day. She is evil, that’s all I know of her, and I vowed never to be in that position again.

Kosta’s Eye, Father Thason, and Contacting the Gods¶

Kosta asks Elmer to study the glowing purple orb that has replaced his eye. Elmer can tell that it’s deeply enchanted with powerful magic, beyond that of mortals.

Kosta then heads off to find the clerics, who help him with the scry spell to try and locate Father Thason, but they are unable to. Without a clear direction, he tries to contact Pelor, to no avail, as Deimos also tries in vain to get in touch with Gargauth.

Sankra’s Ice¶

At Elmer’s suggestion, Nib takes another look through the Celestial book given to them by the General. He finds a passage that mentions:

Moradin’s Might, The Wild Mother’s Clay, Savras’s Eye, at the heart, Sankra’s Ice

The names line up with the four items, leaving Sankra’s Ice to be the Crystal Blade. The group decide to head to Dawn Song’s camp the following day to see what she had left behind.

That night, Nib, Deimos, and Sumunar dream of the black plain again. Around the fire this time is Katrina, the devil, and a pale blue figure. Katrina tells them that the crystal blade is part of the lock, and the group should take the remaining three items back to the door to seal it again, at which point the three magical items they’ve found will be returned to their hiding places.

We Canoe!¶

Leaving Rafael at the fort, the party take a pair of canoes to cross the river’s mouth and avoid going back through the gulch. After the crocodile fiasco, Kosta is put safely inside a magical ball for the journey. They’re attacked on the way by giant sharks, and fight them off with difficulty, but eventually make it to the other shore. Due to the loss of a canoe, Elmer has to ride Qhell (as a Giant Sea Horse) for the rest of the journey.

Campfire Tales¶

They camp on the treeline of the beach. Nib tells stories of their excursions north:

Last time we camped by the sea, was much colder than this. Was up north, near Tressmouth. We’d been hired to go track down the rumours of a lost tribe of elves deep in the arctic tundra. We’d sailed on a old ship, The Orphans Rage, north out of Nook, but hit difficulties about two days out of Northwatch. Ship went down, half the crew lost to the dark waves. Those of us that made it, washed up on this thin spit of land. We burnt what wreckage we could, the flames green with the salt, just to stave off the cold.

As dawn broke, we had to head out. Only 12 of us left then. The cold claimed two more that first day, another the next.

We hit a valley, some shelter from the winds, but soon lost in their midst. We turned one bend and there stood our doom, a dark beast of the ice. It feel on us, blood-stained claws tearing into us. We ran but it was faster. The end was upon us as a thick black arrow sailed into the crevasse. Then another, and another, another. Under the hail, the beast fell, and looking up we saw them, The Lost Elves, bows drawn. Their leader nodded at me, and like that, were gone. Just saved our lives and disappeared into the snow.

Sumunar’s Story¶

“You all know that Jadel and I knew each other,” Sumunar takes up. “We were in nearby villages, and played together sometimes as young orcs. Well, she had a sweet tusk like you would not believe. Always loved a bit of honey or sap-sugar. So one day we were out rambling, and came across a hive high up in a tree. She wanted to raid it, and I was not hard to convince. Well anyways, we got our little selves about halfway up, then realized we couldn’t reach any higher. We tried going back down, but it was at an awkward angle and we couldn’t manage. We must have sat there for three hours, arguing about whose fault it was and yelling for help occasionally. At last I grew so sick of waiting that I jumped down, and naturally broke my wrist. So then she was still stuck, and I was on the ground but holding my wrist and crying. Finally I got it together enough to run to the nearest village, and the grown-ups got Jadel down.” She pauses and laughs fondly. “I forgave her quickly enough, but her nickname was Honey-Tusk for years afterwards.”

A Visit From Elmer’s Father¶

As Elmer takes watch that night, the figure of his father walks out of the water and berates him for running away, tells him to come home. An argument ensues, and Elmer refuses to go anywhere with him.

Sa’khuna’s Statue¶

The next day, on their trek through the forest, the group come across a statue of a long-dead god of the hells, Sa’khuna. Coloured keys sit in locks, and as Kosta plays with them, a loud boom explodes from the statue. The roc approaches from the sky, and the party escape with the help of Jul’s Pass Without Trace spell.

Areka¶

On the outskirts of Dawn Song’s camp, the party rest for the night. Deimos is visited during his watch by a wooden automaton with a black spear. It talks with Deimos, though doesn’t appear threatening. Apparently the roc is called Barda, and it warns of Ghosts to the south, and to stay out of the tunnels.

The Return of Night Bane¶

During Elmer’s watch, Night Bane turns up, limping, draging a broken leg behind them. He has a conversation with Elmer, saying that Kosta killed him from behind, and that he’d come for him. Deimos and Kosta wake, and Night Bane challenges Kosta to a fight. Instead, Kosta talks him down, and then heals him slightly at his request. He leaves to find his partner, claiming that “Vecna is all, and will be all soon”.

Dawn Song’s Camp¶

In the morning, the group confront four figures still at the camp, “Brazen Guard of the Golden Stars, servants to the Undying Mistress”. Elmer fireballs them, which sets the camp alight and starts a fight. Defeating the guards and putting the fire out, they find the same books they have a copy of, as well as an updated map of the jungle with more locations marked. There’s also an annotated book, The Travels of Magil the Lost, Vol 5: Mauldold, Illwind, and the Jungle. Her notes also show that they had found the helm at a shrine at the bottom of the river.

Kosta attempts to talk to Pelor for direction, but is blocked by a voice saying “he can’t hear you, you’re on my land now. She knows where you are now. I’ve told her.” Kosta is overwhelmed by twisting energy pulsing from his eye.

Dawn Song the Necrodragon. Again.¶

In the far distance, Qhell sees Dawn Song lift off from the mountains headed towards the group. Deimos puts Kosta in the ball once more, and lifts off to distract her while the others run for the trees. A brief fight in the air comes to an end when Nib casts Dimension Door to pull Deimos out of the dragon’s way and disappear into the forest.

Safe in the trees, they release Kosta from the ball, returned to normal.

Don’t Smell the Flowers¶

Heading onward through the forest towards a place marked on Dawn Song’s map as Fulgrin’s Tomb, Kosta stops to sniff some flowers, which turn out to be nasty man-eating plants. Fighting them off, the party have to get creative with methods of removing the corrosive sap from their skin without any water to hand.

The Crashed Balloon¶

Further on, they come across a crashed hot air balloon with the skeletons of some elves. Their notes show them to be explorers who had set out long ago to find the lost city of Maudold, and crashed here. Elmer takes a ring, intending to return it to their family one day. There’s also a chest there, with an inscription that indicates it can only be opened at midnight. The party bury the elves, and then camp for the night.

During the night, Qhell is visited by another chwinga like the one that came to Sumunar, which has apparently placed leaves on the graves of the elves. He gives Qhell a ball of twine.

At midnight, they open the chest and find a load of gems, four spell scrolls, a wand, a red amulet, an old map, and a pair of glowing stones. The amulet is to stop somebody from being magically tracked, and the wand helps find hidden doors and compartments. The stones are teleportation anchors. Holding one stone lets you teleport to either of the other two (of which the group only found one).

The Endless¶

Deimos takes a stone, and teleports to the unknown one. He finds himself in a large dusty room, where he is promptly arrested and taken across a large city (Rabbad, later explained by Nib) to talk to The Endless, a tall thin figure with golden skin. He seems to know all about the group, what they have been trying to do, and even talks of the Tabaxi twins sibling, Dusk, who they presume lost. Deimos is given the third stone, and he returns to the others.

Furry Creature Fight¶

While Deimos is gone, the others move on through the jungle, where they’re set upon by small furry creatures. Just as they manage to fight them off, Qhell scaring a few away as a Black Bear, Deimos pops back into existence with them.

Fulgrin’s Tomb Entrance¶

More treking through the jungle, and the group eventual stumble on what looks to be the entrance to Fulgrin’s Tomb. A pile of stone juts up out of the ground, with a jet black door set in it. The clearing is patrolled by several figures in black armour. Talking with the figures, they are told to leave. They will not let anybody “disturb the imprisonment” and won’t say any more. Qhell discerns that they are engraved with binding sigils—something is bound magically within each suit of armour. The group retreat for the night.

Areka, Again¶

Before sleep, Elmer studies the books again and finds mention of “a cave of glass behind a door of nothing” in the Da Dark Under, as well as “the land of their sleep, a black river of death, a battle with The Night”.

That night, Deimos is once again visited by Areka, who tells him and Elmer that the third cat, Dusk, is beneath the jungle, behind that door, attempting to break open the lock without the rest of the key, which he refers to as the Ashes.

As night continues, so does our story. The plan for the morning? To get past the guards, through the black door, and down below to Fulgrin’s Tomb. Are the party nearing the conclusion of their adventure? Are they walking to certain death, and will they all return? Find out… when we do, and I do another write up!

Relay FM for St. Jude

2022-10-02T00:00:00+01:00

September is over, and that means the end of another Childhood Cancer Awareness Month. For the last four years, the Relay FM community has used the opportunity to raise money for St. Jude Children’s Research Hospital, an institution dedicated to understanding, treating, and discovering new ways to defeat childhood cancer. Last year, they raised over $700,000. This year, they’re set to match that amount again, taking the total raised in the last four years to over $2 million.

For Stephen, one of the founders of Relay FM, the cause is particularly important. You can read more about his story and why they fundraise over on 512pixels.net.

When the campaign started last year, I had been a part of the Relay FM members Discord for a few months. People were sharing the fundraising total in the Discord in various ways, and a few enterprising individuals came up with a variety of ways to get that total into a iOS Home Screen widget, such as this Scriptable solution by Zach Knox. At the time, I was just starting to play with iOS app development and I thought “we can do better than this. Let’s make a native app and widget!”

A group of us had already gotten together and built a Discord bot for the server, so I had the perfect group of developers to solicit for help. Together, we built a small app that pulled the campaign information from the Tiltify public API (reverse engineered from their website, rather than the official APIs), displayed it in the app, and provided a widget. It could also pull in the campaign’s milestones. We distributed it via TestFlight, so we didn’t have to deal with full-on App Review, and it was a great success (amongst Relay FM members, at least).

It was a brilliant learning experience for me, and greatly increased my knowledge of how a iOS app is built, albeit a very simple one. I am very grateful to all the people who took the time to explain things to me, and review and comment on my code to help me become a better Swift developer.

This year, we dusted off the app and plugged in the new campaign details a few days before September started, in order to get it up and running again. However, the campaign organisers threw us a last-minute curveball—there wasn’t going to be just one campaign this year, but many! Relay would still have their main one, but anybody could set up “subfundraisers”, all of which would add towards the overall total. So how was the app going to handle that?

We spent some time reverse engineering the Tiltify API for the new campaign format, and reworked the app from a simple “here’s a widget” to a more full-featured discovery app, showcasing not only the overall total but also each individual fundraiser and their own goals and rewards. We extended the widgets to allow you to choose which fundraiser it should show, provided a variety of appearance options, and added a share screen to let users post pictures of the fundraiser progress on social media.

And of course, we threw in Lock Screen widgets and donation charts for those who’d braved the iOS 16 beta, or regular people upgrading when it was released publicly half way through the month.

Throughout the project I’ve learned more about Swift, SwiftUI, and iOS app development than I ever would have working on my own with no real goal in mind. I’ve learned how to handle the various iPhone and iPad screen sizes, store data locally with GRDB, and use custom intents to provide widgets of all sizes with dynamic options.

It’s been a lot of fun to have a project to work on that’s reached so many people (despite never leaving TestFlight!) and helped towards raising the absolutely phenomenal amount that the Relay FM community achieved for St. Jude this year. The app is open source, and we will hopefully be resurrecting it next September when the community comes together once more in the fight against childhood cancer.

UserDefaults, @AppStorage, and Data Types

2022-09-29T00:00:00+01:00

As I’m starting to play more seriously with iOS app development, Xcode, and Swift, I’m starting to come up with a variety of patterns I use in the various toy apps I mess around with that make working with certain APIs or frameworks easier. One of these is UserDefaults, which provides an easy way to store persistent data between app launches.

The basic way to interact with UserDefaults is to set values by assigning a data type to a particular key (which are strings), and reading that key later:

// Storing a boolean value
UserDefaults.standard.setValue(true, forKey: "hasPerformedInitialSync")

// Retrieving a boolean value
let hasPerformedInitialSync = UserDefaults.standard.bool(forKey: "hasPerformedInitialSync")

There are two problems with this, though:

Using string-based keys is error-prone; it can’t be checked by the compiler, so an overlooked typo can lead to unexpected behaviour that’s difficult to debug.
SwiftUI is based around watching state variables for changes, and redrawing views based upon this; how can we tie UserDefaults into that?

A `UserDefaults` extension¶

The first problem is one I’ve started solving by creating an extension to the UserDefaults class. I put this in a new Swift file (usually Extensions/UserDefaults.swift), with code such as the following:

extension UserDefaults {
    enum Key: String {
        case hasPerformedInitialSync
    }
    var hasPerformedInitialSync: Bool {
        get { bool(forKey: Key.hasPerformedInitialSync.rawValue) }
        set { setValue(newValue, forKey: Key.hasPerformedInitialSync.rawValue) }
    }
}

This has promoted the previous string-based keys we were using to an enum: the compiler is now able to check our keys for us and produce errors at compile time if we use one we haven’t defined. An additional computed property on the UserDefaults class hides the get and set logic from us, so in the rest of our code we need only do the following:

// Storing a boolean value
UserDefaults.standard.hasPerformedInitialSync = true

// Retrieving a boolean value
let hasPerformedInitialSync = UserDefaults.standard.hasPerformedInitialSync

Hurray! No more string-based keys to remember. But what about the second problem?

Up until recently, I was syncing UserDefaults changes with SwiftUI view state by storing a related @State variable, and tying it to the corresponding UserDefaults key using onAppear and onChange(of:):

struct ContentView: View {
  @State private var hasPerformedInitialSync: Bool = false
  var body: some View {
        NavigationView {
      // View code
      Button(action: {
        hasPerformedInitialSync = true
      }) {
        Text("Sync Done!")
      }
    }
    .onAppear {
      hasPerformedInitialSync = UserDefaults.standard.hasPerformedInitialSync
    }
    .onChange(of: $hasPerformedInitialSync) { newValue in
      UserDefaults.standard.hasPerformedInitialSync = newValue
    }
  }
}

This works by fetching the value stored in UserDefaults when the view first appears and assigning it to the state variable, and then watching the state variable for changes, and syncing those back to the UserDefaults key. But there are still problems with this:

It’s easy to forget to add the required line to onAppear or the onChange handler for a new variable.
The view won’t react to changes that happen to the UserDefaults key outside of its own interaction, such as if a presented sheet changes the value.

Fortunately, SwiftUI introduced a new property wrapper similar to @State to help us with this.

Introducing `@AppStorage`¶

Called @AppStorage, the new property wrapper lets you reference a UserDefaults key directly and bind it to a variable that will automatically sync changes between itself and UserDefaults. It can be used as such:

struct ContentView: View {
  @AppStorage(UserDefaults.Key.hasPerformedInitialSync) private var hasPerformedInitialSync: Bool = false
  var body: some View {
    // View code
  }
}

Note that there’s no longer any need for the value to be read onAppear, or the changes to be observed using onChange. SwiftUI will take care of that for us, automatically syncing data back when actions within the view change the state variable’s value. Very handy!

Supported Data Types¶

However, there are still limitations with this approach, one of which I ran into today and was banging my head against for quite some time until I realised the issue.

UserDefaults supports the storage of a variety of primitive data types:

Boolean
String
Integer
Data
URL
Double
Float

It also supports storing arrays or dictionaries containing these primitive types, using the array(forKey:), stringArray(forKey:), and dictionary(forKey:) methods. AppStorage, however, does not support this. Apple’s documentation for AppStorage lists the init methods available, and they can return:

String
Integer
Data
URL
Double
Boolean

It’s missing Float—I didn’t care about that—and the Array and Dictionary methods—I did care about those. I had created my UserDefaults extension, as normal:

extension UserDefaults {
    enum Key: String {
        case favouriteColours
    }
    var favouriteColours: [String] {
        get { stringArray(forKey: Key.favouriteColours.rawValue) ?? [] }
        set { setValue(newValue, forKey: Key.favouriteColours.rawValue) }
    }
}

That worked fine, as expected. But when I tried to use it with @AppStorage:

@AppStorage(UserDefaults.Key.favouriteColours) private var favouriteColours: [String] = []

the compiler threw up the error No exact matches in call to initializer. Helpful. It turns out that’s because of the lack of support for the collection methods, and I had to resort to using my original onAppear/onChange workaround.

It’s not all bad, though!¶

Despite this frustrating limitation with AppStorage (which I hope is fixed in a future SwiftUI release), I really like the UserDefaults extension method for working with the API. There’s two more things I want to mention about it. One, it can be used to store or return any data type, as long as you can easily convert it to or from one of the supported types. For example, storing a custom enum is easy. Make the enum inherit from Int or String, and you’re off to the races:

enum Mode: Int {
  case light
  case dark
}

extension UserDefaults {
  enum Key: String {
    case preferredMode
  }
  var preferredMode: Mode {
    get { Mode(rawValue: integer(forKey: Key.preferredMode.,rawValue)) ?? .light }
    set { setValue(newValue.rawValue, forKey: Key.preferredMode.rawValue) }
  }
}

Secondly, if you want to be able to access the data you’re storing in other targets, such as a widget, the extension is a great place to create a static property that uses a group identifier:

extension UserDefaults {
  static let shared = UserDefaults(suiteName: "group.com.myapp.AppName")!
}

Accessing UserDefaults.shared instead of UserDefaults.standard will allow it to be read and written from any targets that have access to the specified group identifier. Additionally, SwiftUI provides two different ways of specifying that you want to use .shared instead of .standard. It can be done on a per-variable basis by passing the store: parameter to @AppStorage:

@AppStorage(UserDefaults.Key.preferredMode.rawValue, store: UserDefaults.shared) private var preferredMode: Mode = .light)

Or it can be made the default for all child views within a hierarchy:

struct MyApp: App {
  var body: some Scene {
        WindowGroup {
            ContentView()
        }
        .defaultAppStorage(UserDefaults.shared)
    }
}

Both of which make working with UserDefaults cross-application much easier.

Anyway, I’m mostly writing this down so that the next time I’m struggling with it I can prompt myself on how it works and why I’ve done things a certain way; but maybe it can help you, too!

Review: 71408 Princess Peach's Castle

2022-09-11T00:00:00+01:00

My final review of this year’s new Princess Peach-themed Super Mario LEGO sets, this time for Peach’s Castle:

71408 Princess Peach’s Castle is the largest of the Peach-themed additions to the Super Mario line this year, and is in fact the largest of all the game’s sets so far at 1,216 parts. It includes a variety of characters, both new to the range and returning, and commands some impressive space when laid out ready to play. Let’s take a look at what’s inside!

Review: 71407 Cat Peach Suit and Frozen Tower

2022-08-05T00:00:00+01:00

I took look at another one of the Princess Peach-themed Super Mario LEGO sets that were released at the start of August:

There’s no doubt that this set is visually striking - it has an impressive height, bright colours, and a baddie flying around on a broomstick. It’s also great to see a costume change for Peach introduced already (and I’m glad that the other characters can use it too—although Luigi did need a software update in order to understand).

One more to go in this batch of reviews!

Elsewhen 1.5: Time Zones, Translated

2022-07-28T09:00:00+01:00

We’ve recently released Elsewhen 1.5, a time zone app that I develop with a group of friends. Jason Snell featured it over at Six Colors:

One app that can help is Elsewhen from The Lovely Developers, a fun group that sprung out of the Relay FM Discord. Elsewhen lets you quickly set a date and time and then translate it — either into a bunch of human-readable time zones, or into Discord’s time-code format.

The latest version not only showcases a brand new UI and the ability to create and save groups of time zones, but also brings it to the Mac for the first time. If you ever have the need to share a given time in a multitude of time zones around the world, or are part of an iternational Discord community where their time codes feature comes in handy, give it a whirl. It’s been a blast working on it.

My D&D Adventures

2022-07-26T15:00:00+01:00

When I first got into D&D a year or so ago, I created my first character for a play-by-post (PbP) game called The Lost Jungles of Rabbad. Since then, I’ve joined other PbP games, played a few live one-shots (via video call), starting running my own PbP game with a pre-rolled adventure from D&D Beyond, fought other players in two player-vs-player (PvP) arenas, and play-tested a couple of new campaign ideas from our DM.

I hope to write more about my characters in the future, but here’s a summary of the games so far.

The Lost Jungles of Rabbad: PbP, playing as Elmer Raloren, a noble-born High Elf Wizard (School of Abjuration). Currently at level 6. A homebrew adventure run by our DM, Rob, in a world of his design. I wrote a summary of this campaign previously.
A Darkness Gathering: PbP, playing as Dagoth the Ancient, a Bugbear Paladin (Oath of the Ancients). Currently at level 5. A campaign that a first-time-DM, Jake, has adapted from an old 2e adventure, I believe. It started out as Frozen Sick, a free sourcebook on D&D Beyond, which the players quickly completed and Jake transitioned.
The Princess Bride: PbP, playing as Stardust Nightwhisper, a Fairy Bard. Currently at level 3. The game was conceived of and run by Nic, who had to put it on pause after he and his wife had a baby! Star, as my character was known by, is waiting patiently for when the game resumes and I can play a bard once more!
The Wave Walker: PbP, playing as Kaith, an irritable Aarakocra Monk. Currently at level 2, the game was started by another first-time DM, Madi, in a world of her own creation. She ended up not having the time to continue it, so it is currently on haitus, but hopefully will return!
The Wave Walker: Windborn Demons: Although Madi didn’t have the time to full a full-blown campaign, she plans to run a series of smaller one-shots for characters in the Wave Walker world, starting with Kaith. The game has only just begun, but I am excited because I was enjoying roleplaying Kaith’s surly demeanour, and am looking forward to attempting to play a monk in combat.
Winter’s Crest: A live playtest of a winter-themed one-shot campaign Rob was writing, playing as Peregrin Puddlefoot, a Halfling Bard, at level 5. The campaign was very fun, and we were successful as a party—although there were definitely times it felt like we weren’t going to be!
The Dragon of Icespire Peak: PbP, where I’m the DM! A pre-rolled adventure on D&D Beyond, I’m having a lot of fun making it my own. The characters are currently at level 3, though they chickened out of completing the latest job, which would have earned them a level bump. One of them was bitten by a Wererat, so they’re currently distracted by that.
The Hawkstone Alliance: A series of live games played in Rob’s world, with a rotating set of players each time. Playing as Tabasco, a level 4 Tabaxi Artificer (Alchemist), I’ve currently been involved in two adventures so far of the four that have been played.
The Pit: The Isle of Death: A PbP PvP game, playing Olrim, a level 10 Fallen Aasimar Paladin Oathbreaker. There were five others in the game, and Olrim ultimately came second, and was so close to beating Skulkas!
The Pit: The Temple of the Light: The second PbP PvP game, this time playing Kolasi, a multiclassing Zariel Tiefling - level 3 Rogue, level 7 Paladin. This is my first attempt at multiclassing, and I find level 10 pretty difficult to work with (there are so many options). We’re working in pairs this time, but it’s not going particularly well for Kolasi or his team mate - somebody brought a pack of bears and a dragon to the fight, which was terribly unfair of them!

We’re also playtesting a new campaign idea from Rob, which I won’t say much about other than it’s not D&D-based this time, but uses fate dice. In the first playthrough I played as Kalamae, Goddess of Life and Destiny, Mother of Creation, Watcher of the Sands, and in the second (currently in-progress) as Sa’khuna, God of the Night and the Underworld, Lord of Darkness, Keeper of the Keys. It’s a lot of fun!

One of the most fun aspects of character creation is their visual design, and Hero Forge is a fantastic place to get inspiration and build colourful 3D models. You can even buy them as STL files or 3D printed figures for your in-person games, though I haven’t done that yet. Here’s what all my characters look like:

I never realised that D&D could be as fun as all this. I have found a fantastic group of people to play with and seeing everybody’s creativity is truly amazing.

LEGO Review: 71403 Adventures with Princess Peach

2022-07-26T00:00:00+01:00

LEGO’s expanding their Super Mario range this summer, and I’ve written a review of the latest character to the lineup, Princess Peach, over on Brickset:

This year, another well-known figure from the Mushroom Kingdom joins the lineup, with 71403 Adventures with Peach! The previous two starter courses were designed to provide everything you need to get going with the range, even if you don’t have the previous sets, and Peach is no different, and is in fact the largest of the three.

The Lost Jungles of Rabbad

2022-07-07T00:00:00+01:00

It is high summer in Illwind, the cool air off the sea balanced well against the heat from the desert to the east. The port town is busier than ever today, with the Feast Of Forgotten Gods in full swing. All throughout the streets, children run with green and yellow streamers, horns and whistles blaring. In the town square, the inns have thrown open their doors, each serving feasts for the revellers, here you see a whole buffalo being roasted, there the largest fish pie you’ve ever seen. The smells and sounds are a heady mix, not to mention the free flowing beer, wine, ale and mead.

Most of the festival goers are gathering around here, to enjoy the food and watch the Momerie taking place there. This year telling the tales of a lost goddess of the plains, who fell in love with a mortal man, and forsook her divine power to live and age and die at his side.

Welcome to Illwind, a small city-state bordering the jungle, the sea, and the desert. This is a town of Rob’s creation, one of many settings in the large world that he’s created as a Dungeons and Dragons (D&D) game master, where he runs many campaigns for experienced and new players alike.

About a year ago, I joined my first Dungeons and Dragons group. It’s something I’d been vaguely interested in, but had never had the opportunity to get involved with. These games were set up by Rob as a way to introduce new people to the hobby, and play in a no-pressure, no-rush environment as text chat in a private Discord server. Play-by-post, as it’s called, means it doesn’t matter that none of our time zones line up, or if we’re busy with “life” - we can play at our own pace, and somebody’s absence only holds up the storyline during the more rigid turn-based combat parts. I eagerly joined, and was grouped together with four others into a campaign called The Lost Jungles of Rabbad, the initial hook being described as follows:

The Jungles of Rabbad are a wild and unexplored wilderness, replete with tales of lost cities, roaming undead and wild forgotten beasts. Two weeks ago, a party from the Temple of Oghma left on a expedition to find a hidden temple. Three days ago, contact was lost. Someone needs to go in and get them....

We then created our characters, starting at Level 2, and put together this band of misfits:

Elmer Raloren, a male High Elf wizard,
Deimos, a male Feral Tiefling rogue,
Sumunar, a female Half-Orc barbarian,
Tylress, the Victorious, a male Dragonborn fighter, and
Kosta Dragonstone, a male Hill Dwarf cleric.

It was a good mix - a squishy spellcaster, a sneaky rogue, a couple of melee fighters, and a healer. It was time to jump in, and start playing the game.

The campaign has now been running for almost a year, and the characters have levelled up from two to six. A lot has happened, some of it following the initial path of the DM’s campaign, and much of it not! I thought I would write up the campaign from the start to where we are now, summarising each event, as a log for future reference.

Alb’s Assignment¶

The characters, never having met each other before, all (except Sumunar) come together in an inn in Illwind, The Half-Turned World, presided over by the barkeep, Undril. New to the others, Tylress is a regular, a place he meets with his friend Sylvie (an elf with severe PTSD). Together, the crew head on down to the docks in search of Alb, a man known in the town for offering coin in exchange for jobs, not all of which are legal.

Joined by Sumunar on their way onto Alb’s boat, The Orphans Lament, they convince Alb of their competence by way of a fight against four animated and armed mannequins. He promises them 30 gold now, and 50 gold on return, for delivering a chest to Fulsi at the Farr Inn.

After deceiving Alb’s minions and getting 45 gold out of them instead, they head off to the south towards the inn, a midpoint on the road between Illwind and Barrow’s Edge, a journey of a few days.

Nib and Jul¶

During the second day on the road, the group meet a pair of elves, destined for Barrow’s Edge, and they fall into travel together. These are the siblings Nib, a white-haired bard, and Jul, a mute monk with some unknown dark magic about her. The group learn that the pair have been hired by The General (the leader of the barracks town Barrow’s Edge), on a “dangerous and urgent” mission, so of course Deimos offers their services.

Tylress is less than convinced about Jul, warning the rest of the group against her, which almost results in a fight on the road.

The Farr Inn¶

At the inn, Elmer greets Fulsi (to whom he apparently owes coin), and they take the chest round to the barn at the back. Fulsi runs an illegal fighting ring from here, and Sumunar taps in to take her turn in a bout, losing to a tall goliath, Xeri. Exhausted, the party all retire to bed.

Tylress is woken in the night by Jul, gesturing to him to head outside in the rain. She challenges him to a fight, to put their previous quarrel behind them. It’s tough, but Tylress is victorious, knocking Jul unconscious.

In the morning, the party awake. Deimos finds a small bronze coin with a compass engraved on it tucked in his pack - the assumption is it came from Nib, but Nib denies all knowledge of it.

Bandits on the road!¶

On the road from the Farr Inn down to Barrow’s Edge, the party is stopped by a group of figures in green uniforms, two mounted on horses. They demand a toll for usung the road, “in the Queen’s Name”. The group doesn’t fall for this, and a fight breaks out. The bandits are dispatched, along with one of the horses (unfortunately), and Elmer takes over looking after the other horse, whom he names Rafael.

The bandits all have matching tattoos on their wrists of golden stars, that Kosta recognises as the mark of an undead cult that’s been operating out of the jungle. Rumours say they’re trying to build an army!

Kosta calls upon Turn Undead, to make sure there are no undead around. Nothing happens, other than Jul winces as the shockwave from the spell passes over her.

As night falls, the party share some of the elves’ wine. Sumunar is plagued by dreams of burning cities, of skeletons crawling out of shallow graves, of shambling undead clawing at her face, and Nib sleeps badly, but nobody else is affected.

Barrow’s Edge¶

Reaching the city after lunch, Nib leads the group to meet with The General, a white dragonborn. She presents them with a rough, old map of the jungle, and tasks them with the following:

“The other planes are slowly encroaching on us, and this is where we believe the key, and the lock, are. I need you to go here, find the key, find the lock and seal the gates again.”

They’re looking for the source of the weak points in the lines between the planes of existence, and they sent in two sets troops to deal with it. They were all lost, only one person returned.

The group are given three old texts relating to the jungle:

The Fulgrin Lament, written in Infernal. Fulgrin is a old myth, a fallen angel who raised a host against the gods of old, but banished to a distant plane.
Da Dark Under, written in Orcish. It appears to be the written history of an orc warband.
Written in Celestial, it’s a collection of divine rituals and rites.

Kosta heads to the infirmary to go and talk with the only surviving member of the scouting group, a green tiefling called Hoc. She’s missing a hand and an eye, and constantly speaking wordlessly, but uncommunicative.

Kosta contacts some celestial power, a being that appears to speak through him, who pours energy into Hoc to help her speak:

…from beneath one by two by one beneath the trees and the screams and the dark deep deeper deep…

The group learn they’d been in the jungle for a week or so, lost their healer to a group of undead, who they’d then followed south to the river, where there was a long abandonded camp across the water. They found an altar, headed down some dark, wet steps beneath it, that just ended abruptly.

Kosta’s new celestial patron then helps heal the tiefling, replacing her missing eye with a jet black orb, before the Barrow’s Edge healers step in.

The Celestial¶

Kosta reveals that the past few days he’s been … communing with a higer power. The Celestial, some kind of god/demon, is able to take over Kosta’s body, and speak through his voice. This appears to be the result of some kind of deal, details are scarce. It was the source of the power that helped heal Hoc, and it is quite happy to help in destroying any undead.

It also does not seem to like Jul. It has told Kosta she is “touched by darkness”, and that the group needs to “deal with her”. Elmer’s unable to get anything out of Nib, other than vague talk of dangerous missions “up north” to look for a lost tribe of elves; and likewise Deimos out of Jul.

That night, Deimos tails Jul to a building in Barrow’s Edge, which appears to be a tailors. She returns emptyhanded. Breaking in, Deimos finds nothing untoward inside.

Into the Jungle¶

The next morning, Nib’s been looking through the book written in celestial, and reveals that there is talk of binding spells that “lock” gates between the planes, and how to maintain them. This has previously been done at “the hollow of the world”.

Jul disappears, and returns with a black bag slung over her shoulder. She doesn’t mention it, other than to say it contains “supplies”.

The General presents the group with a set of cloaks that offer some camoflage in the jungle, and after obtaining a slightly better-drawn map from the local cartographer’s, they set off, heading into the jungle in the general direction of a wizard’s tower marked on it.

There’s no path through the jungle, the group having to pick their way over the tree roots etc. Passing a tree with an ancient small golden star carved into it, similar in design to the bandits’ tattoos, they stop to let Elmer cast a ritual to detect magic. The star glows of abjuration and enchantment, and there’s a similar one in trees to the north and the south, forming a sizeable magic circle, amplfying some arcana within, serving as a ward of the area.

Tylress destroys the magic in the star with his greatsword, with seemingly no effect to the rest of the sigils, and the team pass through further into the jungle.

The Clearing¶

The group comes to a clearing, which contains a large stone ring with four pillars surrounding it. Three of the pillars have a glowing red stone atop them, slowly pulsing. As Deimos circles the clearing to get a better look, the party are attacked by the vines, and have to fight hard to free themselves and clear the creatures. Deimos spends much of it poisoned and entrapped, with Kosta dolling out regular healing.

Kosta’s patron seems to believe it’s being caused by “the darkness in Jul”.

Eventually the creatures are cleared, the last one running into the foliage and disappearing. Poking about, a fourth red crystal is found on the ground, while Elmer scales a pillar and investigates the stone altar. It turns out to be some kind of teleportation circle. The group decide to rest for the night before activating the circle with the fourth crystal, and the conversation turns to their life stories.

Tylress’ Story¶

Tylress sighs “Fine, if nobody will tell my story then I will tell it myself. I’m sure many of you have met a variety of Dragonborn, but us reds are a particularly warfaring lot. Like my brethren I rose through the ranks, conquest after conquest. Everyone loses a battle, but I never lost a war. It’s how I earned my title of “The Victorious”. But I have honor, and I will not commit atrocities for the sake of it. Unfortunately others do not share this mindset. They see the blood and death as sport. And since I hadn’t yet reached the highest rank, there were plenty of bastards above me who would rather have their fun than honor. One day, I was instructed to lead my men into a village of elves and to slaughter them all. Men, women, and children. I refused. My commander seemed to be waiting for this moment. I was set up. Apparently, he felt threatened by a younger and more skillful warrior. He had me arrested and charged with insubordination. I was stripped of my rank and banished.”

Deimos’ Story¶

Deimos hesitates for a moment and takes a long drink before sighing. “I suppose I did start this. Well I was born a poor devil child and have no idea where I’m actually from or any of those little details. I was a foundling near a small provincial farming village by a wonderful human family. They overlooked…well all of this…” he indicates his wings and rather demonic appearance. “They raised me alongside their real daughter as a member of the family and taught me some of the finer arts.” He nods to to cook pot. “They made the decision to hide my appearance from the locals, which seems insightful considering what comes next. I attended the small human school and survived as the sickly child in robes. On the farm at night I was encouraged to fly and stretch my wings. All was good until…that day. I was in school as usual as for some reason a fire broke out at the school. As the students were running out, I heard a scream from within. As became apparent in that last fight, I enjoy a certain resistance to fire so I ran back to help. Well I may be resistant but not so much the robes.” Deimos is clearly uncomfortable at this point. “I was able to pull the boy out, but…didn’t make it in time. He didn’t survive, and neither did my disguise. I probably don’t need to detail what happened when the not-particularly open minded townsfolk saw…well me…carrying a dead child from a fire that isn’t having any effect on him.” A bit of sadness combined with anger is apparent now. “Well there’s a reason I’m not a huge fan of pitchforks. The mob realized who I was and proceeded to the farm. I was…too late to save my parents, but managed to pull my sister [Marlena] out before they could get her. I flew us as far and fast as I could. In the chaos of the next few days we were separated. I’ve been on my own, surviving and trying to find out what happened to her since then.”

“I’ve gotten pretty good at the survival part, but haven’t really made any progress on the other, and generally don’t stay in one place long enough to…enjoy…a similar reception.” Deimos is very clearly out of quips at this point and sits in silence, taking another long drink.

The Blackened Figure¶

During Deimos’ shift, a figure steps out into the clearing, a figure only he can see. A man, about Deimos’ age, half his face burnt away. He tells Deimos that they met, many years ago, and it was Deimos who did that to him, and that he will always be there waiting for him. None of the others in the group are able to see or hear the figure.

Deimos tells the others, believing it to be the boy he tried to save.

During Kosta’s shift that night, he casts Detect Magic, and sees that Jul glows brightly with necromancy, and the bag she is carrying with abjuration magic. He fights with his patron, The Celestial, who wants him to fight Jul and take her out. An internal argument between two higher powers happens within him.

In the morning, he confronts Nib about it, who is defensive and protective of his sister. Nib reveals that Jul has done a deal with something, something Kosta or The Celestial find distasteful, but that it is not their business. She is not evil or corrupt.

Teleportation¶

Deimos and Elmer use mage hands to place the crystal atop the final tower, and a dark space appears in the middle of the ring. Obviously, the group all jump through!

They find themselves in the basement of a half ruined church or temple, still in the middle of the jungle. The alter glows with a magic of an unknown school. It’s engraved with an incantation of an offering to The Dark One, possibly relating to Kiaransalee, a now-dead Drow god of revenge and undeath.

Crocodiles¶

The group leave the temple, and head towards the sound of running water. They soon come to a river, which they attempt to swim across but are beset by giant crocodiles. It’s a tough crossing, but they make it to the other side.

Katrina¶

The land this side is less jungle, more swamp. There is a large clearing to the south, with many gravestones made of reclaimed wood dotted across it, arranged in a wide spiral, culminating at a handful of buildings in the middle. Somebody watches them from a shaded porch, and Deimos approaches, hailing them. Their name is Katrina, they are a survivor from The Eli Flyer, a ship that ran aground. The rest of the crew are marked by the gravestones, and Katrina says she remains here to keep the woods nearby free of bodies, lest the Golden Hands raise them as undead - the cult with the star tattoos.

She seemingly doesn’t realise that the graves are in a spiral, and says that she cannot find her way “out”. Deimos offers to help, once the group’s current mission is completed. Elmer determines that the place is infused with enchatment magic, and Katrina herself with transmutation magic. He confronts her about this, and she says she will release Deimos from his enchantment when they have destroyed a red crystal atop a nearby tower, which will remove the binds keeping her there.

Having little choice, they head towards the tower she indicated.

Elmer’s Invisible Man¶

That night, during Elmer’s shift, a figure steps into the clearing, invisible aside from an outline against the trees. As Elmer approaches, it says nothing but:

HELP I. YOU HELP I. I YOU. I ARE YOU. HELP…

It disappates at Elmer’s touch.

The Red Hammers’ Tower¶

The tower sits within a square clearing, about five stories tall, with a red glow at the top. The top stories are half-exploded, with the chunks of masonry blown out but hovering in mid-air, as if the explosion had been paused. Deimos attempts to talk his way into the tower, but (of course) it turns into a fight, with the guards calling Katrina “the defiler”, and it is their duty to keep her bound.

During the fight with the guards, an enormous bird (a roc) joins the fight, causing trouble for Deimos’ usual flying tactics. The group dispatch the guards, but one flees. Nib is pushed from the top of the tower, and hits the ground, dead. Deimos blames himself, for his enchantment causing them to head to the tower. Kosta blames himself for abandoning his cleric path making a deal with another patron.

Deimos destroys the crystal, and with it, the entire tower collapses. Tylress grabs Nib, picks him up, and runs off into the trees. Jul takes Rafael and follows. The others rest, badly hurt.

Tylress takes Nib back to the clearing with the graves, to Katrina. All the graves are on fire. In return for a future favour, she is able to bring Nib back, though he is not quite the elf he was before. He is cold, his eyes misty, his skin grey.

Deimos’ Dream¶

The others make it back to the clearing, finding Jul lost in the woods. Resting for the night, Deimos finds himself on an endless plain of black sand, where he meets Katrina, an old man, and a devil around a campfire. They call themselves allies against oblivion, saying their name is Gargauth. They thank him.

In the morning, Kosta reveals he is familiar with the name Gargauth, as the Tenth Lord, the banished Lord of Hell.

Zombie T-rex¶

Sounds of movement lead the party to a clearing, where a load of zombie workers are clearing out a mine entrance, guarded by a group of living overseers, including a tabaxi that they had tracked riding a zombie t-rex. Deimos flies over, invisible, and sees they are pouring over a map. The group attempt to forge the map and swap it, but the swap goes badly and they end up fighting a load of zombies and the zombie t-rex ridden by the tabaxi, Night Bane. The rex also keeps vomiting up more zombies. It is a tough fight, with Elmer being seriously injured by the dinosaur, but they are victorious with the help of a jar of eyes that Sumunar had, turning into a pack of wolves when smashed.

The tabaxi is tied up, unconscious. When he wakes, Deimos enchants him to believe the group are his friends, and he tells them that he “serves at the pleasure of Vecna”. The zombies were digging to search for the key, otherwise known as “the Bone”, which fits “everything, and opens the whole of creation to The Ascended One”. He reveals the location of their current base. The team untie him, but as he is walking away, Kosta swings his warhammer (newly-acquired from the tabaxi himself) and hits the cat, Sumunar following up with a killing blow.

The Map¶

After studying the map the party retrieved, Nib translates the text on it. There are four circles surrounded by text in Celestial, with the smaller circles also written in Abyssal:

Big circle, bottom left: In The Dark, Seek The Light, Open The Door
Top left: The Scale Needs Balance, The Scale Demands Fire
Top right: The Deep Is The Core, The Door
Bottom right: The Star Shall Die, The Stone Frost

Kosta’s Freedom¶

Ashamed by his behaviour regarding the tabaxi, Kosta pleads with his patron Pelor to be free from his deal with The Celestial. He’s struck by a blinding white light, and wakes to find he feels free of the influence of the second god.

The Mine¶

Deimos is told by the old man from his dreams that going down the mine is going to be bad. “Take light. It’s less… underneath the world, more like between.”

The party take a long rest, but during the first watch Tylress feels the mine calling to him, and heads down into it, first on steps, then climbing down ropes. Deimos and Sumunar also feel the pull, but Nib and Elmer slap them out of it. They head down after Tylress, who has found his way to a rubble-filled tunnel, which he starts clearing. Deimos heads down after him, and they have an argument, but eventually come back out, and they all complete their rest.

All down in the mine the next day, crossing some black water, Tylress, Kosta, and Sumunar are dragged below into the inky blackness, and disappear. At this, the party is split.

Deimos, Elmer, Nib, and Jul¶

Continuing on, the party are attacked by a pair of basilisks, which turn Deimos and Nib to stone. After defeating them, Jul and Elmer explore the rest of the mine, finding more red crystals, which they destroy. At each impact, their reality shifts briefly into an alternative space, and then snaps back. At one point, Jul also vanishes and Elmer is alone. He eventually finds her and helps save her from a gelantinous cube.

Tylress, Kosta, and Sumunar¶

The three fall through into a small circular room, with a red crystal high above. Exploring through the door, the find other rooms, and some statues of a tiefling and an elf - Deimos and Nib, presumably. They also smash red crystals they find, after one of which Kosta disappears in a flash of bright light. Eventually, Sumunar opens a door and find themselves face to face with Elmer and Jul…

The Staff and Dawn Song¶

Suddenly, a bright blinding light fills the area and Deimos and Nib return from stone, but trapped in a cage. Sumunar is back with Elmer and Jul, Kosta and Tylress have disappeared…

They find their way to the room which Deimos and Nib are caged in, and fight a swirl of ink that’s protecting a staff in the middle. They escape with the staff, out the mine, only to be met by Dawn Song, who fights them for the staff. Deimos is enchanted, and attacks Nib, and the party give up the staff to save themselves. Dawn Song disappears into the jungle.

Fulgrin’s Lament¶

During a rest, Deimos discovers a couple of passages from the Fulgrin’s Lament book:

“…and the cowards bound him there, by staff and by blade, by hammer and by helm, rather than face their own failures…”

“…the ashes, cross-bound about his gate, the wood and glass and steel and gold, held tight by the elemental keys, his door bound, waiting to rise again…”

The Camp¶

They find Dawn Song’s camp - another open mine, mostly undead; giants, dogs, and dinos. Dawn Song has the staff and the helm. During the night, Elmer creeps over to watch and sees them sacrificing some figures in a number of fires, while the rest chant.

Meanwhile, Deimos dreams of the endless plain again, and is told:

These items are parts of the key that will unlock the door. Taking them from where they were held has started to unlock that door. If they get all three, and reach the door, they will open it fully. They will need collecting, and taking to that door to relock the door too. The Crystal Blade is not part of the key, it is part of the lock. As you might expect, it’s location is hidden from the likes of us. Last we heard it was in the mountains. The stolen dead will know, seek their camp, it has what you need.

The Mountains¶

In the mountains, the group find The Dark Sun, a glowing black orb of nothingness inside a volcano crater. While there, they are ambushed by Dawn Song and her crew of undead and skeletons.

In the fight, Deimos touches the black orb, and disappears. Elmer, Sumunar, and Nib die. Deimos is transported to an endless desert of sand, and finds man sitting beneath a tent at a table. They play a game of cards, Deimos is given a steel warhammer, and is returned to the volcano holding a card. Using the card, Deimos brings Sumunar, Elmer, and Nib back from death. They fight again, and Dawn Song leaves with the staff, promising to come back for the hammer.

To the Red Hammers¶

The party decide to go to the Red Hammer’s base at Fort Hope and ask for help. On the way, they pass the body of the Red Hammer that fled the tower earlier, killed by arrows, half his face dissolved. The ground gets swampy and they are set upon by a group of frog creatures. They fight them off, and later come across an enormous snail being ridden by mice. This is Meile, a travelling tradesperson. The group pay for passage on the snail, Bessy, to Fort Hope.

Qhell¶

At the fort, the group are given bed and board by Jadel, the leader, a friend of Sumunar’s. They also offer their help, and that of their clerics, in the fight against Dawn Song.

Also at the fort the group meet Qhell, an Aarakocra Druid. He is there as a guest of the clerics, and joins the party in their campaign.

Fighting Dawn Song. Again¶

Finally, Dawn Song attacks the fort to retrieve the hammer. She brings many zombies, including zombie aarakocra, velociraptors, giants, and an ankylosaurus. The fight is tough, and seemingly not going their way, when…

Kosta Returns!¶

A break in the clouds forms, and from it, you see a pillar of light streak down and strike the earth next to Jul. Shielding your eyes, you can see something zip down, crashing to the ground with a thunderous force. The light fades, and you see a dwarf adorned in shining armor. His hair is a brilliant white, and he’s missing an eye, but as he turns to you and smiles, you recognize him instantly.

Kosta returns from the heavens! His Turn Undead proves incredibly effective, and eventually the tide of the battle turns and the group defeat the zombie hordes.

The Necrodragon¶

Just as Dawn Song is killed:

As last of her life force drains away, you hear her whisper, “I am ascended....”

As her body slumps to the floor, the blood and viscera that lines it begins to slowly boil. You all see around you, all the bodies and blood, mortal and undead jerk and wither before you, their blood being drawn deeper in to her. And you see her body start to twist, and bulge, a pair of black skeletal wings burst from her back, her claws distend into long talons, with a sickening crack her back breaks and grows, and in her place stands a haggard and undead dragon, it’s skin white as her fur and her eyes a deep shimmering blue. She looks around at you all, and with a deep roar akin to the creaking of a crypt, she lifts into the air, and flies off, limping as she does.

In her wake, she leaves behind the helm, the staff, and various other belongings.

The Story Continues…¶

And that is where the group is currently up to! We have many questions to answer as we continue: is Dawn Song actually dead? Will the Necrodragon return? Where is the Crystal Blade and can the party find the door and lock it once more?

The story continues to play out in it’s typical PbP fashion, with ebbs and flows. Maybe in another year (or sooner!) I’ll write up another update here, but for now… you’ll just have to wait and see, won’t you?

I'm into pens

2022-07-05T00:00:00+01:00

I’m into pens. There, I said it.

I’ve always had a vague, background interest in writing and writing implements. As a child, I had a couple of “teach yourself calligraphy” books, a few calligraphy pens, and I enjoyed finding excuses to use them: writing up the menu for tonight’s dinner, a sign for my bedroom door, etc. But then computers happened and I started writing by hand a lot less, and when I did, it was with whatever cheap biro happened to be close by.

Fast forward a few years (too many than I’d like to count), and in 2020 I joined the Relay FM members Discord. This was a place where people who enjoyed the variety of podcasts that Relay FM offered could socialise and discuss the topics that interested them; I joined mainly because they talked about it so much on Upgrade and Connected, and it seemed like a good place to find new people to chat with.

Turns out, I’ve made some of my best friends there. People I talk to every day, who know me better than I know some “in person” friends that I’ve known for years. But these friends have been a bad influence (on my wallet, at least).

There’s a channel in the Discord for each rough topic that the Relay FM shows cover. For example, there’s #tech, #apple, #creativity, #systems-and-themes etc. It makes sense, then, that there’s a #pens, given that there’s an entire show on Relay FM dedicated to them—The Pen Addict. I’ve listened to the show a couple of times, but it’s not one I’m subscribed to, and it never totally grabbed me. However, people sharing photos of their fountain pens, beautiful handwriting in stunning inks, letters they were writing and sending around the world—I wanted in.

I resisted for a while, I didn’t need another hobby to suck up what disposable income I had. So I started small—I asked for suggestions on a daily pen that could replace my cheap biros, nice to write with but nothing fancy. Madi suggested the Zebra Sarasa, and a three-pack dropped through the letterbox shortly afterwards. I was blown away! These were so much nicer to write with than what I’d been using before, and I was back to finding excuses to write by hand. I took to carrying one around in my pocket (a habit I’d never had before), along with a Field Notes pocket notebook that Madi had kindly sent across the ocean to me, in a package that also contained a whole host of different coloured refills. I was in.

One of the other members of the Discord, Ellen, had started up a small pen pals group, an offshoot from the official Relay Discord. I joined the group and wrote a couple of letters with the Sarasas, but really I wanted a fountain pen and everything that came with it - the little bottles of ink, the choice of nib size, the process of flushing, cleaning, and refilling, etc. So I asked for advice, took the plunge, and bought a TWSBI Eco Clear, and a bottle of TWSBI 1791 Orange ink. I mean, how else was I going to get to write in orange?!

It arrived (along with a packet of Love Hearts and the invoice held together with a little colourful smiley face paper clip, nice cute touches from Cult Pens) and I quickly filled it with the ink and started writing. Needless to say, I love it. I had chosen a medium nib, because I don’t like too skinny or too fat writing, and the only thing letting my letters down now is my handwriting!

Fast forward a few months, and I’m itching for a new colour. Don’t get me wrong, I love the orange, but I also fancied a nice vibrant pink. So what was I to do? How could I get the pink, without giving up having the orange easily to hand?

Clearly, the answer was to get a second fountain pen. (I see how this snowballs, now…) Ellen recommended another starter pen, the Lamy Safari, which I ordered in pink, with a broad nib this time. (It does need a converter to use bottled inks, as it usually takes a cartridge.) I also intended to add a bottle of Lamy Crystal ink in Rhodonite, which is a vibrant pink, but when the order arrived it turned out I’d actually somehow clicked on Agate, which is a rather flat grey. I was somewhat disappointed!

Contacting Cult Pens, they were happy for me to return the Agate and they would send out a replacement Rhodonite, which was very kind of them. I packaged the ink back up and took it off to the post office.

Ellen and another friend from the Discord, Alex, had been listening to me whine about not getting the pink, and a surprise package dropped through my letter box a day or so later. Opening it up, it contained a bottle of Robert Oster Signature ink in Hot Pink! Unbeknownst to me, they’d conspired to order me a replacement themselves, and chose Robert Oster in part because it’s good ink, but I suspect mostly because it’s Australian, and so is Ellen. They have a truly enormous range of colours, and the Hot Pink is fantastic. Exactly what I was after! It’s also in a 50ml bottle, which will last me literally forever.

However, I was still going to be getting a replacement of the Lamy Crystal Rhodonite, so I contacted Cult Pens again and asked if they could instead send out a different colour (despite Ellen’s protestations that two pinks is not too many pinks, I want a nice range of colours before I start doubling up and comparing!)

They agreed, and so we come to today: I have a TWSBI Eco (M) inked in Robert Oster Signature Hot Pink, a Lamy Safari (B) with a tiny amount of Lamy Crystal Agate, and a bottle of Lamy Crystal Amazonite (a really lovely turquoise blue) on its way. I can’t wait to try that out.

The only question is: now I have three ink bottles, and just the two pens. There’s only one solution, surely…

Python and the Magical OAuth Token

2022-04-25T00:00:00+01:00

A recent post by Colin demonstrated a utility class they’d written to handle fetching and refreshing OAuth bearer tokens for APIs and services that are secured that way, to stop you having to worry about it in the majority of your code. For years, I’ve used a similar class at work that I wrote to simplify this, and Colin’s post prompted me to share it here too.

The main difference from Colin’s solution is that the class I use is a subclass of the Requests Session object, rather than a stand-alone object. It handles not only fetching and refreshing the bearer token where necessary, but also inserting the correct headers to the requests you make. Here’s the entire class (and a couple of helper exception classes):

import requests
import datetime

class OAuthResponseError(Exception):
    pass

class OAuthInvalidGrant(OAuthResponseError):
    pass

class OAuthInvalidScope(OAuthResponseError):
    pass


class TokenRefreshSession(requests.Session):

    ERROR_MAPPING = {
        "invalid_grant": OAuthInvalidGrant,
        "invalid_scope": OAuthInvalidScope,
    }

    def __init__(self, client_id, client_secret, scope, token_url, *args, **kwargs):
        self.oauth_client_id = client_id
        self.oauth_client_secret = client_secret
        self.oauth_scope = scope
        self.oauth_token_url = token_url
        super().__init__(*args, **kwargs)

    def prepare_request(self, request):
        '''Add the access token to the headers'''
        self.headers["Authorization"] = f"Bearer {self.oauth_access_token}"
        return super().prepare_request(request)

    @property
    def oauth_access_token(self):
        '''Return a valid Access Token. Renews the token if it has expired'''
        if not self.oauth_access_token_valid():

            data = {
                "client_id": self.oauth_client_id,
                "client_secret": self.oauth_client_secret,
                "grant_type": "client_credentials",
                "scope": self.oauth_scope,
            }
            headers = {
                "Accept": "application/json",
                "Content-Type": "application/x-www-form-urlencoded",
            }

            response = requests.post(
                self.oauth_token_url,
                data = data,
                headers = headers,
            )

            response.raise_for_status()
            response_data = response.json()

            if "error" in response_data:
                raise self.ERROR_MAPPING.get(
                    response_data["error"],
                    OAuthResponseError)(response_data["error_description"]
                )

            self._oauth_access_token = response_data["access_token"]
            self._oauth_access_token_expiry = datetime.datetime.now() + datetime.timedelta(seconds=response_data["expires_in"])

        return self._oauth_access_token

    def oauth_access_token_valid(self):
        '''Check the validity of the current access token'''

        now = datetime.datetime.now()
        fudged_time = now + datetime.timedelta(minutes=5)

        access_token = getattr(self, "_oauth_access_token", None)
        access_token_expiry = getattr(self, "_oauth_access_token_expiry", now)

        if not access_token or access_token_expiry <= fudged_time:
            return False

        return True

The code is relatively simple. As a subclass of requests.Session, it accepts all the usual arguments, but also requires the OAuth client ID, client secret, scope, and token endpoint. This could be hardcoded, or a default provided in the class definition as we do internally, to avoid having to specify it each time.

The prepare_request method is part of the requests.Session mechanism for generating the HTTP call when the library is used. The overriden method in the TokenRefreshSession object inserts the correct Authorization: Bearer header and token into the request on behalf of the user.

As with Colin’s solution, the oauth_access_token property is computed when accessed, and performs the necessary update or refresh should the currently stored token have expired, by posting the client credentials data to the token endpoint provided.

Here’s an example of the class in action:

session = TokenRefreshSession(
    client_id="123456",
    client_secret="shh",
    scope=["read", "write", "etc"],
    token_url="https://api.my-great-app.com/v1.0/auth",
)

user = session.get("https://api.my-great-app.com/v1.0/users/23")

The first API call will fetch the token and store it, and subsequent calls (using the same session object) will either use the stored token or fetch a new one as necessary. You never need worry about including the Bearer header yourself. And, to quote Colin’s post:

Your token will magically manage itself, leaving you free to write good code against your favorite API.

LEGO 71374 Nintendo Entertainment System

2020-08-17T00:00:00+01:00

Beyond my budget (for now!), but the new NES LEGO set looks fantastic:

71374 Nintendo Entertainment System achieves extraordinary realism, potentially surpassing any previous LEGO model in that regard. The external detail is absolutely spectacular and the designers have made splendid use of existing elements to recreate distinctive shapes from the NES. I am particularly delighted with the controller and the casing around the connection ports on the console, both of which could be mistaken for their real equivalents.

Hopefully it will be available in the LEGO employee store when I visit Billund for the 2021 Inside Tour next year!

Junos commit history: who did what?

2019-11-16T00:00:00+00:00

Junos has always had one fantastic advantage over Cisco’s IOS: the ability to stage a pending commit, and see a history of changes, rather than each command immediately being executed on the running config a soon as you hit Enter.

The show | compare rollback X command has always been able to show you the difference between your current config and what the config was like X commits ago. However, I’ve always found it difficult to figure out what exactly was done in a single commit (or batch of commits) if they weren’t the most recent. That is, until I learnt of this command: show system rollback compare X Y! This lets you see the changes that were introduced just between the X and Y commits.

Here’s a real life example. Below is the commit history for a device at work. You can see there were a number of batches of commits going back in time where different individuals have done sole changes on the device:

ben@switch> show system commit
0   2019-11-13 15:06:51 GMT by katerina via cli
1   2019-11-13 14:49:19 GMT by katerina via cli
2   2019-11-13 14:43:01 GMT by katerina via cli
3   2019-11-13 14:42:11 GMT by katerina via cli
4   2019-11-13 14:41:01 GMT by katerina via cli
5   2019-11-13 14:03:53 GMT by katerina via cli
6   2019-11-13 12:28:33 GMT by katerina via cli
7   2019-11-13 12:25:44 GMT by katerina via cli
8   2019-11-13 12:24:53 GMT by katerina via cli
9   2019-11-13 12:23:28 GMT by katerina via cli
… output truncated … 
20  2019-09-13 14:16:43 BST by ben via cli
21  2019-09-13 14:15:27 BST by ben via cli
22  2019-09-13 14:13:48 BST by ben via cli
23  2019-09-13 14:13:06 BST by ben via cli
24  2019-09-13 14:08:43 BST by ben via cli
25  2019-09-13 14:08:13 BST by ben via cli
26  2019-09-13 14:06:50 BST by ben via cli
27  2019-09-13 14:06:12 BST by ben via cli
28  2019-08-07 14:21:33 BST by stuart via cli
29  2019-08-07 14:21:08 BST by stuart via cli
30  2019-08-07 14:18:43 BST by stuart via cli
31  2019-08-05 09:06:28 BST by stuart via cli
32  2019-06-19 13:04:54 BST by lewis via cli
33  2019-06-19 13:02:34 BST by lewis via cli
34  2019-06-19 13:01:31 BST by lewis via cli commit confirmed, rollback in 3mins
35  2019-06-19 12:59:30 BST by lewis via cli
36  2019-06-19 12:58:39 BST by lewis via cli
37  2019-06-19 12:58:03 BST by lewis via cli commit confirmed, rollback in 3mins
38  2019-06-07 13:58:39 BST by bart via cli
39  2019-06-07 13:07:17 BST by bart via cli commit confirmed, rollback in 1mins
40  2019-06-06 12:27:51 BST by bart via cli
41  2019-05-15 13:07:07 BST by chris via cli
42  2019-05-09 14:14:43 BST by chris via cli

I needed to find what Stuart and Lewis had each introduced in their batches of changes back in August and June, respectively. This new command makes that trivially easy.

Stuart’s batches of changes were in commits 28–31. Running the following command, I was able to easily extract just what those commits introduced:

ben@switch> show system rollback compare 32 28
[edit interfaces interface-range ir_stp_edge]
     member ge-0/0/10 { ... }
+    member ge-0/0/6;
+    member ge-0/0/7;
+    member ge-0/0/8;
… more changes …

Note that you need to put the higher (older) commit number first, followed by the lower (more recent). Additionally, you need to increase the higher commits number by one, as you want to know what was introduced between those commits, including the oldest one.

Likewise, to see what Lewis introduced in his commits, we can run the following:

ben@switch> show system rollback compare 38 32
… some changes ...

This will definitely save me some time in future!

Tiny Git Tip

2019-10-10T00:00:00+01:00

Brandur, on Twitter:

Git tip I wish I’d discovered ten years ago: if you git config --global diff.noprefix true it removes the silly a/ and b/ prefixes so that when you double-click select one to copy, you get a usable filename instead of a mangled path.

This is something I’ve always been annoyed by—I’m so glad there’s a fix!

NASA Administrator Remembers Mission Control Pioneer Chris Kraft

2019-07-23T00:00:00+01:00

Chris Kraft, NASA’s first Flight Director, died yesterday, two days after the 50th anniversary of the first man on the moon.

Once comparing his complex work as a flight director to a conductor’s, Kraft said, ‘The conductor can’t play all the instruments–he may not even be able to play any one of them. But, he knows when the first violin should be playing, and he knows when the trumpets should be loud or soft, and when the drummer should be drumming. He mixes all this up and out comes music. That’s what we do here.’

It’s almost as if he waited for the anniversary. The world remembers the names of the men who set foot on the moon, but Chris Kraft was another hugely important person managing the hundreds of highly skilled engineers and scientists without whom the moon landing would not have been possible.

We’re fast approaching a time where there will be nobody left who was involved in project Apollo. It will never be forgotten, but it will be sad to no longer be remembered first hand.

Self-Host Your Static Assets

2019-07-11T00:00:00+01:00

Harry Roberts, writing at CSS Wizardry:

One of the quickest wins—and one of the first things I recommend my clients do—to make websites faster can at first seem counter-intuitive: you should self-host all of your static assets, forgoing others’ CDNs/infrastructure. In this short and hopefully very straightforward post, I want to outline the disadvantages of hosting your static assets ‘off-site’, and the overwhelming benefits of hosting them on your own origin.

I’m a little late to this (the post was written back in May), but it’s an interesting counter argument to the common practice of serving third party resources from a provider’s CDN. The post goes into a lot more detail, but if you can, host it yourself.

The Two-Napkin Protocol

2019-07-07T00:00:00+01:00

An interesting piece of history I didn’t previously know.

It was 1989. Kirk Lougheed of Cisco and Yakov Rekhter of IBM were having lunch in a meeting hall cafeteria at an Internet Engineering Task Force (IETF) conference.

They wrote a new routing protocol that became RFC (Request for Comment) 1105, the Border Gateway Protocol (BGP), known to many as the “Two Napkin Protocol” — in reference to the napkins they used to capture their thoughts.

The post is worth a read just to see the photos of the napkins. I’ve never really thought before about how RFCs come to be. I’d always assumed they were the result of clever people in offices, not really thought up on the back of a napkin over drinks!

Also, as it’s 2019… happy 30th birthday, BGP (and the World Wide Web).

The Infrastructure Mess Causing Countless Internet Outages

2019-06-29T00:00:00+01:00

Roland Dobbins from Netscout Arbor, quoted in this Wired article:

“Nonspecialists kind of view the internet as this high-tech, gleaming thing like the bridge of the starship Enterprise. It’s not like that at all. It’s more like an 18th-century Royal Navy frigate. There’s a lot of running around and screaming and shouting and pulling on ropes to try to get things going in the right direction.”

It’s amazing how fragile some of the technologies that power something the world takes for granted are; BGP is a great example of that. The Internet is everywhere, and it’s becoming increasingly more necessary to be connected in order to be able to just go about our lives.

Regarding the choice of headline, however, I don’t think the word “mess” is fair. That does a disservice to the hundreds of very talented people that design, implement, and maintain the infrastructre that underpins our connected world.

Junos: Confirm a commit cleanly"

2018-07-27T00:00:00+01:00

For years, I have loved the fact that Junos allows you to perform a commit confirmed to apply the configuration with an automatic rollback in a certain number of minutes.

I have always believed that the only way to confirm the commit (i.e. stop the automatic rollback) was to commit again. This creates two commits in the commit history, one containing the actual config diff, and an empty one purely used to stop the rollback. I’ve always thought that this creates a somewhat messy commit history, and confuses the use of show | compare rollback:

{% highlight bash %} [edit] ben@device> run show system commit 0 2018-07-27 08:44:26 BST by ben via cli 1 2018-07-27 08:44:07 BST by ben via cli commit confirmed, rollback in 5mins 2 2018-07-23 10:04:29 BST by ben via cli 3 2018-07-23 10:03:58 BST by ben via cli commit confirmed, rollback in 2mins

[edit] ben@device> show | compare rollback 1

[edit] ben@device> # Huh, it’s empty?! I’m sure I did some work…

[edit] ben@device> show | compare rollback 2 [edit system] - host-name old-device + host-name device

[edit] ben@device> # Oh, there it is…

However, today I learnt that a commit check is enough to stop the rollback, and doesn’t create an empty commit! My commit histories are now much cleaner, and show | compare rollback commands a lot easier to work out what you’re actually looking at.

{% highlight bash %} [edit] ben@device> run show system commit 1 2018-07-27 08:44:07 BST by ben via cli commit confirmed, rollback in 5mins 3 2018-07-23 10:03:58 BST by ben via cli commit confirmed, rollback in 2mins

[edit] ben@device> show | compare rollback 1 [edit system] - host-name old-device + host-name device

Much better!

Lessons Learnt from an Outage

2018-07-22T00:00:00+01:00

I caused an outage last week.

Not intentionally, and not a large outage by any stretch of the imagination. But it had various knock-on consequences that led to a lengthy application recovery time, long after full network connectivity was restored.

We were replacing one of the two core MPLS routers at one of the three primary sites in our network. Upgrading the hardware to a newer model required costing the existing node out, powering it off, physically replacing it with the new hardware, and bringing the node back online.

(For those of you interested in the details, we were upgrading a Juniper MX480 to an MX10003 - all logical connectivity was staying the same, but some links were being upgraded from 10Gbps to either 40 or 100).

In preparation for the upgrade, I had taken the running config from the existing node, adapted what was necessary for the newer hardware (mainly interface name changes, etc) and preloaded it onto the new node waiting in the lab. So far so good.

Unfortunately, the running config at the time I took it from the live node, was exactly that - the live node. At that moment, it wasn’t in its costed-out state, meaning that the minute we started repatching links into the new hardware, they were coming back live.

These core node provide connectivity between our three primary sites, and their three data centres. As the links came up live, the new node started drawing traffic from the local data centre fabric before it had any connectivity to the other sites (or even the other node in the same site). This meant that for a period of around four minutes, between one sixth and one half of all egress traffic from the local data centre was being blackholed, and dropped.

This caused connectivity issues between our ceph clusters, which then struggled to make sense of the situation, and filled up the only remaining link between this site and the others with traffic. (I don’t know the full details of why it did this, or what that traffic was - I’m a network engineer, and not responsible for the rest of the infrastructure. But remember I said we were upgrading from 10 to 100Gbps on some links? This is partly why). This then exacerbated the connectivity problems (for other applications in addition to ceph), pinning the links at line rate long after the we had costed out the new node as originally intended, leading to the long recovery time for the application layer.

So what did I learn from this outage? That’s the most important question when something like this happens - particularly if it was your fault. This is what I learnt.

Don’t become complacent¶

We had done this exact procedure for the other node in this site just days before, and all had gone smoothly (I had remembered to cost out the new node as I was preparing its config, instead of running with the live config from the existing node). Even if you’ve done an identical change before, always triple check what you’re doing if it has the potential to cause an impact on other parts of the business. Ideally, ask a colleague if they can spot anything you may have forgotten.

Unconditional summarisation isn’t always a good thing¶

Even though the links weren’t costed out, if all the core did was pass on routes learnt from the other sites, then the new node wouldn’t have started drawing traffic until it was able to route it.§

Instead, our core currently advertises three aggregate routes to its clients - the three private RFC1918 ranges. These aggregates are active if just a single contributing route is present in the routing table. In our case, the core node’s loopback is a perfectly valid contributing route to the 10.0.0.0/8 aggregate, causing it to be advertised even if every other link on the box was down, drawing (and dropping) traffic.

Under normal circumstances, we’d obviously expect the core nodes to have full reachability to the rest of the core, and this wouldn’t be an issue. However, certain failure scenarios can cause a node to become isolated (not just configuration mistakes like this one!) and blackhole traffic. Advertising more specific routes actually learnt from other peers, or some conditions imposed on the generation of the aggregate routes, would help limit this.

Be selective about the order links are repatched¶

Core-facing links first! The outage was caused by the fact that the links to the data centre fabric were connected before the core-facing links. If they had been done the other way around, and core connectivity as part of the MPLS domain was confirmed before connecting any client-facing links, the issue would have been avoided.

Core-facing links are more important than client-facing - most clients will have redundancy via other nodes, and even if they don’t, until your core node has reachability to the rest of the core, it’s useless to its clients anyway.

Don’t neglect CoS¶

While not directly related to the outage itself, ceph filling the links with non-essential traffic (compared to, say, production web or database traffic) led to outages on other applications that could no longer communicate. Some quality of service markings and traffic shaping or policing would have a gone a long way to mitigating the impact, by restricting non-business-critical traffic to a subset of the link. Less important (but still useful) on the upgraded 100Gbps connections; but our single 10Gbps like couldn’t cope.