Posts // AJ Kueterman

A Little More Prompting

Fri, 28 Aug 2026 00:00:00 GMT

I've spent a little more time building with the ML Kit GenAI Prompt API on Android, which has continued to evolve even since I started playing around with it earlier this summer.

Two notable pieces I wanted to touch on were system instructions and structured output. Each is a tool for engineering better prompts and building more specific user experiences.

[!NOTE] Both system instructions and structured output were added in com.google.mlkit.genai-prompt:1.0.0-beta3

System Instructions

System instructions help you shape the output & tone of your prompt responses. You can define a style, format, or constraints that are consistent across your dynamic queries.

In my D&D Assistant app I added system instructions to help guide my responses in both tone and format.

val SYSTEM_INSTRUCTION = """  
    You are a Dungeon Master's assistant inside a D&D 5e SRD reference app.
    Every message you receive is one SRD entry. 
    Reply with exactly ONE sentence of at most 30 words, and nothing else.
    Lead with the single most important fact a DM would want at a glance, favoring hard numbers and mechanics:
    damage, AC, HP, saves, DCs, ranges, durations, uses. 
    Never open with "This" or a restatement of the title. 
    No preamble, no markdown, no second sentence — output the sentence alone.
""".trimIndent()

I then used this instruction when generating content with a dynamic prompt.

val prompt = Prompt.userContent(entry) // my dynamically generated prompt
val request = generateContentRequest(  
    systemInstruction = SystemInstruction(Prompt.SYSTEM_INSTRUCTION),  
    text = TextPart(prompt),  
) {  
    temperature = 0.2f  
    candidateCount = 1  
}

This helped guide my prompts in a repeatable way so I could get consistent output across many different rules entries I needed to summarize.

Remember to keep system instructions brief & direct. They should be under 100 tokens and clearly state your persona, output shape, or constraints.

If your use case is complex enough that you're reaching for the Prompt API over one of the other feature-specific APIs like Summarization, chances are you'll want to define your output in a repeatable way. System instructions should be a core part of that strategy.

Prefix Caching

If you've done some digging into this API you may also have seen the concept of prefix caching, which allows you to define a re-usable prefix for your prompts that get cached for future queries. This is primarily a performance feature, designed to handle large prompt instruction prefixes.

The guidance is to not use system instructions with prefix caching, and instead decide on the right approach for your prompt workflow. Use prefix caching over system instructions when you have to repeat a large (500+ token) prefix on each prompt to optimize for performance.

Structured Output

Text output is great, but the Prompt API is capable of generating all sorts of text, including structured text - like JSON. This is a super powerful aspect of LLMs that enable them to do all sorts of novel things, and is available on device as well via this API.

The structured output API allows you to define an output class for a given prompt. You can define your object structure, including hints for the model, and then provide that along with your prompt.

Let's define a simple object structure that could be used to convert a monster entry into a summary data model for my summary card.

import com.google.mlkit.genai.schema.annotations.Generable
import com.google.mlkit.genai.schema.annotations.Guide

@Generable("Top level information about a D&D monster")
data class Monster(
    @Guide(description = "The common name of the monster")
    val name: String,
    
    @Guide(description = "The monster type, like undead, fiend, or humanoid.")
    val type: String,
    
    @Guide(
     description = "The monster total HP or hit points.",
     minimum = 0.0,
    )
    val hitPoints: Int,
    
    @Guide(description = "The monster AC or armor class rating.")
    val armorClass: Int,
    
    @Guide(description = "The monster's initiative modifier.")
    val initiative: Int,
    
    @Guide(description = "An optional list of immunities like Acid, Prone, etc.")
    val immunities: List<String>?,
)

Then you can define this output model when prompting. The supported types/constraints cover object types you'd typically deal with.

val promptText = "<Monster block text>"
val baseRequest = GenerateContentRequest.Builder(
	text = TextPart(promptText)
).build()
val typedRequest = generateTypedContentRequest(
    generateContentRequest = baseRequest,
    outputClass = Monster::class, // Define the output model
)

The result is a populated Monster instance, fully populated by the model!

You can do a lot with structured JSON objects. The possibilities are endless for inputting information with well-built prompts, allowing an LLM to process / expand upon them, and generate output models that your app can understand.

Maybe the outputClass is a data model tuned as state for your UI, so that users can input queries to the LLM (via text or app interaction) and the app responds by updating its UI? Ask a question, render a button. I think this could be really powerful!

Overall I'm so excited about the possibility of on-device AI. It makes this technology much more affordable and accessible for smaller apps like the ones I enjoy building.

The Prompt API feels like the true star of the ML Kit GenAI APIs. The features being added continue to support more specific workflows, while giving devs more flexibility on model output. I encourage you to dive deeper and let me know what you're building on Mastodon or Bluesky!

Building a D&D Assistant with On-Device AI on Android

Sat, 22 Aug 2026 00:00:00 GMT

Earlier this year, Google announced Gemini Nano 4 is available as a Preview release via the AI Core Beta. This means developers can start building for Nano 4 to provide fully on-device AI experiences for their Android apps.

As Gemini Nano advances and starts to add more and more powerful models, I've been asking myself how I could harness this on-device advantage to deliver unique experiences.

[!NOTE] Gemma vs. Nano Gemma 4 is Google's latest iteration of Gemma, its powerful open model. Nano packages the small variants of these models into AICore for use on Android devices.

The DM's Assistant

I love playing tabletop roleplaying games. Mostly Dungeons & Dragons 5e. Ever since I got into the hobby, I've mostly been a dungeon master.[^1] The DM is the one charged with guiding the story and adjudicating the rules of the game.

As a DM, one of the hardest things to manage is having the right rules on-hand at the right time. Players are always going to try to grapple the Giant Spider at the weirdest moments. Usually this means either quickly googling rules or flipping through a rulebook.

I've always wished I could have an assistant sitting next to me at our game listening to the flow of play and making sure the right information was always at my fingertips. The major challenge being that D&D happens in person or through a huge array of digital tools, and few DMs have the same setup. You could probably integrate with Roll20 to follow the flow of the game, but then you'd have to do something different for campaigns on D&D Beyond or when your group all meets in person.

If your phone could listen to you (and, optionally, your players) talk through the flow of the game, there may be a way to reason about what rules you need to see when. On-device ML/AI would make listening easier, and summarization could make the information glanceable so that you'd never have to take your focus off the roleplaying.

So I decided to see how I could apply these (now more powerful) Nano-based APIs to this fun problem.

Nano APIs

First I got a bit more familiar with what was possible with Nano 4. For Android developers, access to this model is available via the ML Kit GenAI APIs...I'll refer to these as the "Nano APIs" moving forward.

The key features of these APIs are text-based processing like Summarization / Proofreading / Rewriting, Image Descriptions and Speech Recognition. There is also a more general 'Prompt' API for generating text content from text-based multimodal prompting, which has some powerful implications for prompt engineering.

Based on this list, I decided using a combination of Speech Recognition and Summarization might enable me to build something that has been on my wish list for a while now.

Revelations & Limitations

After some initial experimentation, I quickly learned a few things that would shape this project.

All of the Nano APIs use the same underlying model running inside AICore on the Android OS. This means they are competing for requests, and the API enforces limits on your app. If you want to use Nano 4-based voice recognition while also using it to summarize, you're quickly going to be throttled.
The Summarization API is very strict about its output. It summarizes text as a bulleted list. This restriction, plus some restrictions on how you send summarization requests, made me look to the more flexible solution - prompting.

The impact on this demo was straightforward. Drop the Nano-based speech recognition pipeline and use the more general Prompt API to generate glanceable rules.

ML Kit / Nano Combined Pipeline

Here are the core pieces of the app's processing pipeline, from the DM to relevant rules summaries, with my specific caveats called out.

Speech Recognition
Rules Lookup
Custom Summarization

Speech Recognition

The GenAI Speech Recognition API supports both Basic and Advanced modes.

Advanced mode provides similar functionality to Basic, but its use of Gemini Nano gives broader language coverage and natural language reasoning.
Advanced mode only runs on Pixel 10 devices (with more in development), while Basic runs on most Android devices with API level 31 and higher.
Because it uses AICore, Advanced mode is subject to the model bottleneck issue when put in contention with my summary requests.

With these callouts in mind, I decided Basic would be good enough for my needs in this case. We run speech recognition in a loop, capturing every utterance to be used as keywords in our rules search.

Rules Lookup

As mentioned before, a lot of the complexity of this app comes from the actual lookup of search terms in the D&D rules database.

[!NOTE] SRD Database A piece of the app that I don't go into detail here is the SRD[^2] 'ingest' functionality. The app downloads a copy of the 5e rules database at build time to build its local SQLite DB of rules entries.

As voice input is converted into text, this text is then converted into search terms used to query this D&D database of rules. This logic mostly lives in my TopicExtractor class, which processes each utterance - "the goblin ducks behind cover" - and cleans it into search terms to query the database with.

The actual DB search uses Full Text Search 5 with the built in bm25 function to properly search & rank SRD entry hits. Lists of hits are de-duped before rendering them to the screen, so the user isn't spammed with duplicate rules entries as they talk through the game.

I mention this section specifically because just the combination of Basic Speech Recognition and a powerful SRD database search delivers a ton of value. The final piece, which actually utilizes AICore and Nano 4, is like the last 10% polish on the idea.

Custom Summarization

As mentioned earlier, the Summarization API is very specific about its input and output. Pass in raw text content, and get out 2-3 bullet points in summary.

For the case of my summary text, I wanted to have a 1-2 sentence summary in prose as the output. Maybe not a huge difference by itself.

However, I also am dealing with a slightly different type of content as input. Depending on what type of SRD rules entry I get back, I may want to add that as context to generate the summary text. This added flexibility is something that doesn't exist within the Summarization API, but is offered with the Prompt API.

Here's a real example from the demo app, where typeHint is something like "spell", "monster stat block", or "condition".

val prompt = 
  """  
  You are a Dungeon Master's assistant. 
  Summarize the following D&D 5e SRD $typeHint in ONE sentence (max 30 words). 
  Lead with the single most important fact a DM would want at a glance. 
  Do not preface with phrases like "This $typeHint…"; start with the substance.  
  
  Title: ${entry.name}  
  Body: $body  
  """

This helps tailor our output to exactly what we want to see for each summary.

[!NOTE] Device Support Prompting is available on the same devices that Summarization is available for - usually the latest flagships +1 generation - but which version of Nano it uses depends on the device. Pixel 9 gets Nano 2 (or Nano 3 Preview), and Pixel 10 gets Nano 3 (or Nano 4 Preview) and so on.

Once we define our prompt, we use the ML Kit GenAI API to get a GenerativeModel of our choosing. Here we are specifying that we want to use the PREVIEW version of the model (to get us access to Nano 4 on our Pixel 10) and that we want to use the FULL version (as opposed to FAST).

private val model: GenerativeModel = Generation.getClient(  
    generationConfig {  
        modelConfig = ModelConfig.builder()  
            .apply {  
                releaseStage = ModelReleaseStage.PREVIEW  
                preference = ModelPreference.FULL  
            }  
            .build()  
    },  
)

Then we can use this GenerativeModel directly to generate a text response based on our prompt.

val response = model.generateContent(prompt)

The actual response is a list of candidate text content. Each response type is a piece of output text and a 'finish reason' - like STOP or MAX_TOKENS. In our case we'll use the first result and only inspect the finish reason if there is no valid text.

val text = response.candidates.firstOrNull()?.text?.trim().orEmpty()

This is really all there is to prompting at its core - input text via Prompt and get text content back. The magic happens inside the LLM, and there's a ton you can do with good prompts.

Here's the full code for my implementation of the summarize function from my GenerativeBackend. You can see here that there is some logic to handle serializing calls to generateContent, as my app may have many calls to summarize text happening in quick succession.

// Serializes every inference: the single AICore runtime rejects overlapping  
// generateContent calls with RESPONSE_PROCESSING_ERROR.
private val inferenceMutex = Mutex()  
  
override suspend fun summarize(entry: SrdEntry): String = withContext(Dispatchers.IO) {
    prepare() // Check model availability status & call `model.warmup()`
    val prompt = Prompt.summarize(entry)
    val response = inferenceMutex.withLock { model.generateContent(prompt) }  
    val text = response.candidates.firstOrNull()?.text?.trim().orEmpty()  
    if (text.isEmpty()) {  
        val reason = response.candidates.firstOrNull()?.finishReason  
        throw IOException("Prompt returned no text for ${entry.name} (finishReason=$reason)")  
    }
    text
}

The View Model managing my app's timeline UI manages calling my GenerativeBackend for each new card to summarize its rule content as they populate. The result is a constantly updated list of rules ready to glance at as we need them.

Demo App

Just to give you a working idea of the semi-finished product, here's a demo of the app handling the following prompt.

“Suddenly, a goblin jumps out and attempts to grapple you. You spot another goblin behind cover in the bushes, holding a hand crossbow. What do you do?”

“I cast fireball!”

position: relative;
display: flex;
justify-content: center;
padding: 3rem 0;

}

A 1-bit style radial burst: every dot is drawn at full opacity, so the
fade comes from the dot grid getting sparser as it reaches further out,
not from transparency. / .demo-short-dither { position: absolute; top: 0; bottom: 0; / Bleed past max-w-prose; the layout's overflow-x-hidden clips any spill. */ left: 50%; width: 160%; transform: translateX(-50%); }

.demo-short-dither i { position: absolute; inset: 0; background-image: radial-gradient( circle at center, rgb(var(--demo-short-glow)) 0.5px, transparent 0.5px ); background-size: var(--dot-gap) var(--dot-gap); /* Hard-edged cutoff keeps the grid 1-bit: a dot is either on or off. */ -webkit-mask-image: radial-gradient( ellipse var(--dot-rx) var(--dot-ry) at 50% 50%, #000 99%, transparent 100% ); mask-image: radial-gradient( ellipse var(--dot-rx) var(--dot-ry) at 50% 50%, #000 99%, transparent 100% ); }

.demo-short video { position: relative; max-width: 100%; border-radius: 12px; }

.dark .demo-short { --demo-short-glow: 96 165 250; } </style>

Conclusion

I'm really happy with how this app turned out! I've been playing with it for awhile and I feel like it does a good job, particularly with 'Rules Glossary' type lookups that are most often the 'edge-cases' in a game.

Hopefully this gives you some inspiration to build your own Android experiences with Nano 4 on-device AI. The ability to send open-ended prompts gives you a ton of flexibility to tailor your LLM use to your app's specific needs.

Thoughts on my approach? Questions? Suggestions for what to build next? Let me know on Mastodon or Bluesky.

[^1]: I found that it was a lot easier to get a group together if you offer to DM.

[^2]: SRD stands for 'System Reference Document', which is the official rules document for D&D 5th edition licensed under the Creative Commons.

Dark Sun 2027 is... Gross.

Sat, 01 Aug 2026 00:00:00 GMT

I just wanted to state for the record that the new Dark Sun setting for D&D 5.5e is gross. From the tone of the announcement trailer, and subsequent art/cover releases, it's violent, gory, and mature. That doesn't make it cool.

Announced just this week at Gen Con, D&D is bringing back the Dark Sun campaign setting first released 35 years ago in 1991. Dark Sun was a post-apocalyptic 'Mad Max'-style world where there are no gods, magic is inherently destructive, and life in these wastes is brutal, cruel, and desolate. Already some kind of edgelord-y stuff there.

But in the original setting there was a nugget of something more fun and familiar. The art of Gerald Brom gave everything a bit more of a sense of weirdness, fantasy and...sexiness? (in that 90s sort-of way). It feels like a mix of gritty realism with some sci-fi fantasy layered on.

Just look at some of the art from this 'fantasy Mos Eisley' era of Dark Sun:

And compare that to the 'rivers of blood', Doom-esque reincarnation in the 2027 art:

.dark-sun-gallery img { display: block; height: 300px; width: auto; margin: 0; padding: 0; border-radius: 8px; object-fit: cover; flex-shrink: 0; align-self: flex-end; transition: transform 0.2s ease; }

.dark-sun-gallery img:first-child { margin: 0; }

.dark-sun-gallery::-webkit-scrollbar { height: 8px; }

.dark-sun-gallery::-webkit-scrollbar-track { background: transparent; }

.dark-sun-gallery::-webkit-scrollbar-thumb { background: rgba(0, 0, 0, 0.2); border-radius: 4px; }

.dark .dark-sun-gallery::-webkit-scrollbar-thumb { background: rgba(255, 255, 255, 0.2); } </style>

Gone are the smooth mega-quads and the pointy fingernails. The desolate wastes seem to be replaced with hellish metropolises and alien destruction. Blood, dismemberment, and heavy metal are all that we are left with. So original.

Honestly I'm not trying to go to bat here for the original Dark Sun setting too hard. The truth is it was problematic in more ways than one, and going back to it in 2026 (as I am coincidentally doing right now with my gaming group) requires some adaptation and recognition of the issues.

That said, at least it had a point of view that felt fresh, and still does today. What we're being fed now by Hasbro is something else entirely, and feels like it'll be Dark Sun in name only. I'm good.

Catch me next year playing Star Wars D&D instead.

LitraSwitch

Mon, 04 May 2026 00:00:00 GMT

Some of the best software I use solves a problem that is already "solved" in other ways.

I had a minor inconvenience in my desk setup that could be mostly solved by using existing tools. The ability to turn off/on my Logitech Litra Glow light with a click of a button.

Yes, I could lean slightly forward in my chair to reach over my monitor and press the physical button. Yes I could download the bloated Logitech Options software and click thru a menu to do it. Yes I could pop open a terminal and use the awesome open source CLI to do it, or even auto-toggle the light if I had my camera on or not.

But that's not exactly what I wanted. I wanted an always-available button in my menu bar that I could tap to flip on the light.

So I built LitraSwitch to do just that. Toggle your Logitech Litra lights with the click of a button.

It allows you to toggle all of your Logitech Litra devices on/off with a button in your menu bar. Customize color temperature and brightness in preferences. More features may come - if I ever need them.

If you're exactly like me, and this solution helps you, check it out. If you enjoy it - let me know on Mastodon.

Well Then, Who's Building It?

Sun, 22 Feb 2026 00:00:00 GMT

I've been in my head about the new world of 'agentic AI'. Gas towns and Wiggums, Open Claws and acquisitions. Hacker News is ablaze with AI news / think pieces from every conceivable angle.

In my corner of the world, it seems like developers are mostly on the cynical end. Mourning the death of the software engineering discipline and marking the beginning of the SaaS apocalypse. Calling out how AI is causing RAM shortages which are quickly expanding to storage, and how this is just another way that AI companies are wrestling computing from our hands.

But some are sharing their journey into this new world with enthusiasm and optimism. With the help of Claude & Codex, indie dev veteran Steve Troughton-Smith has been cranking through new apps seemingly by the dozen, including porting iOS apps to Android purely with prompts. I've seem similar threads from SwiftUI pro Simon B. Støvring with caveats. Just to name a few.

In my own experience, Claude has helped me ship updates to both OctoNote and fuzZzy in a matter of days after years of inactivity. There's something incredible about sitting down with a clear product vision, a little bit of basic developer awareness, and access to Claude Opus. No roadblock seemed insurmountable.

But you can't help but feel like there are thousands of other developers doing the exact same thing. Thousands more are taking it a step further with agent orchestration, vibe coding hundreds of thousands of lines of code on their way to the next big software scheme. It can feel overwhelming when you're not min-maxing your own time by coordinating the machines to further your own personal ends. Especially when it feels like hardship is on the horizon for professional software engineers.

All of this brings me to my question. Which is essentially this: <br><br>

What are we, as software craftspeople, doing about this existential threat?

Good people should be making software

Simply put, if software is exponentially more build-able by more people than ever before, then more of us should be collectively building the products and platforms that we want to use and build for.

I think this goes for everything. Social media, email & documents, file sharing, chat & collaboration, operating systems & app stores. If we have this window where AI use is relatively cheap (to the end user) and can accelerate smaller (better, more "good") dev teams to build exponentially bigger products much faster, then that's what I would love to see happen.

I guess I just wish that I was hearing stories about new software startups using AI to rebuild Discord or Gmail or whatever with an ethos that supported privacy, sustainability, and openness. Less stories about the existing powers that be weilding the threat of AI to hurt us.

We should be building collectively, and holding the line

I don't know if the answer is 'open source' in a true sense - maybe it is - but I just feel like we should building this new software in the open in a way that it can't be abused in the name of pure profit for the powers that be.

I think we should find a way to share our AI-accelerated code with each other - the software craftspeople & workers - so that we can compete and build new things that can compete with the giants.

And we should celebrate people who value that mission, and hold strong.

Policy

Ultimately, we need to regulate. It's very disturbing to me how the rise of Gen AI is happening in an era where our leaders are actively ignoring the threats posed by these billionaire-backed would-be monopolies. It's very dystopian, very cyberpunk in the most drab and dangerous way possible.

We need leaders who can identify how to support the average person as AI has immediate impacts, and keep an eye on the horizon for what this technology is going to be and what our place in the new future is.

Summatim

I'm no expert, and mostly just had to get this off my chest. Still processing a lot, and surely will for a long time moving forward. If you read this and felt anything, let me know on Mastodon.

OctoNote 2.0

Wed, 17 Dec 2025 00:00:00 GMT

.app-store-badge { height: 60px; width: auto; display: block; }

.dark-mode-badge { display: none; }

.dark .dark-mode-badge { display: block; }

.dark .light-mode-badge { display: none; } </style>

In 2018 I got to go to WWDC, which was an incredible experience. I had so much fun. I still vividly remember sitting in the convention hall at one of the long wooden tables with my headphones on, jamming to the WWDC playlist, and banging out a new iOS app after having attended a few sessions on the new OAuth libraries & text API's.

.wwdc-gallery img { display: block; height: 300px; width: auto; margin: 0; padding: 0; border-radius: 8px; object-fit: cover; flex-shrink: 0; align-self: flex-end; transition: transform 0.2s ease; }

.wwdc-gallery img:first-child { margin: 0; }

.wwdc-gallery::-webkit-scrollbar { height: 8px; }

.wwdc-gallery::-webkit-scrollbar-track { background: transparent; }

.wwdc-gallery::-webkit-scrollbar-thumb { background: rgba(0, 0, 0, 0.2); border-radius: 4px; }

.dark .wwdc-gallery::-webkit-scrollbar-thumb { background: rgba(255, 255, 255, 0.2); } </style>

I had been annoyed all week at flipping back and forth between Apple Notes on my phone and GitHub gists on my laptop to take notes during sessions. At the time I had been bouncing around between all sorts of note-taking iOS apps that had markdown support, but there wasn't a perfect solution out there. One that offered a great iOS and desktop experience for editing markdown notes. There were apps that did it, but none that I enjoyed using.

Basically I just wanted to be able to take notes on GitHub in the browser as GitHub gists and access them on my phone, which didn't exist. Even now, the GitHub first party app doesn't have great gist support - and they defintely don't focus on using gists as a way to edit & share markdown.

So that's what I was working on that week. A way to view & edit my GitHub gists on my phone. That app eventually became OctoNote, which shipped later that year.

.octonote-gallery img { display: block; height: 400px; width: auto; margin: 0; padding: 0; border-radius: 8px; object-fit: cover; flex-shrink: 0; align-self: flex-end; transition: transform 0.2s ease; }

.octonote-gallery img:first-child { margin: 0; }

.octonote-gallery::-webkit-scrollbar { height: 8px; }

.octonote-gallery::-webkit-scrollbar-track { background: transparent; }

.octonote-gallery::-webkit-scrollbar-thumb { background: rgba(0, 0, 0, 0.2); border-radius: 4px; }

.dark .octonote-gallery::-webkit-scrollbar-thumb { background: rgba(255, 255, 255, 0.2); } </style>

Over the course of the next year or two, I shipped some enhancements to OctoNote, but otherwise it's been largely dormant. Over the last couple of OS releases, stability has gotten progressively bad, including issues with auth at startup that would block users from using the app normally. Time to either shelve it or update it!

It wasn't the first time I'd given myself that ultimatum and inevitably kicked the can down the road. But this year, with the power of Claude Opus to help me plan and execute my app update vision, I was able to carve out just enough of my limited personal time to dedicate myself to updating the app. Claude enabled me to quickly hurdle previous stumbling blocks I had with my limited/aging iOS experience. It saved me from a ton of boilerplate writing and helped me focus on the product vision. Maybe most critically, it helped me reason through the arcane rules of the App Store and some of Apple's APIs that still lack good documentation for newcomers.

The result is a very familiar OctoNote, but one that works and is updated for the latest versions of iOS & iPadOS (+ macOS via Catalyst). Old IAPs and subscriptions work as they did before, similar upgrade features exist for general parity with version 1.1, and, in general, the app is just the same but more stable. I'm honestly proud of how similar it is to my original vision, and how it still holds a valuable place in my workflow.

In the future, I hope to continue iterating on the value prop of OctoNote while bringing people some cool new features. I hope you'll follow along!

Getting games from your Mac to your PS2

Sat, 22 Nov 2025 00:00:00 GMT

There aren't great guides out there for PS2 modding using a Mac. This guide just covers the steps I went through to format my SSD and get games on it from my Mac. Nothing fancy here.

What I used

A Free McBoot (FCMB) Memory card
1TB SATA SSD
SATA to USB adapter
SATA to PS2 adapter

Format the Drive Using Your PS2 Using uLaunchELF

Install your SSD into the network adapter and connect it to your PS2
Boot your PS2 with the FMCB memory card
Launch uLaunchELF (also called wLaunchELF) from the FMCB menu
Navigate to FileBrowser → MISC → HddManager
The HDD Manager should detect your new drive and show it as unformatted
Press R1 to open the menu
Select Format (choose 48bit HDLoader if you get an option)
Wait for formatting to complete

After formatting, your drive has the correct APA partition scheme and is ready for games.

Part 2: Compile hdl-dump on Your Mac

Prerequisites

You'll need:

Xcode Command Line Tools (if not installed: xcode-select --install)
Homebrew (if not installed: visit https://brew.sh)
GNU Make (install via: brew install make)
Git (pre-installed on Mac / with Xcode tools)

Clone and Compile hdl-dump

Open Terminal and run:

# Clone the repository
git clone https://github.com/ps2homebrew/hdl-dump.git
cd hdl-dump

# Build with `make`
make RELEASE=yes IIN_OPTICAL_MMAP=no

After compilation, you'll have hdl_dump executable in the folder.

Connect the SSD via USB

Connect your SSD to your Mac via your USB-to-SATA cable
Important: macOS won't mount the drive (it's APA format) — that's expected, ignore warnings
Find the drive's device path:

diskutil list

Look for your 1TB SSD. It will be something like /dev/disk4 (the number varies). You should make sure it's the exact right size as your SSD and clearly isn't an important / other drive. Be absolutely certain you identify the correct disk!

Install Games

List installed games on the HDD:

sudo ./hdl_dump toc /dev/diskX

(Replace X with your disk number)

Install a game:

sudo ./hdl_dump inject_dvd /dev/diskX "Game Name" /path/to/game.iso

For CD-based games (some PS2 games are on CD):

sudo ./hdl_dump inject_cd /dev/diskX "Game Name" /path/to/game.iso

Verifying Installation

After installing games, verify they're on the drive:

sudo ./hdl_dump toc /dev/diskX

You should see your games listed with their names and sizes.

Sorry to my PR reviewers

Tue, 11 Nov 2025 00:00:00 GMT

I just want to take a moment to apologize to my awesome colleagues who review my pull requests with amazing diligence, care, and kindness. I just need to say I appreciate you and your patience, for dealing with my particular brand of branch-pushing and PR-staging.

I’m a Lion

My preamble - I’m a Lion Chronotype, meaning that I start (early) with energy and lose steam over the course of the day. So my productivity looks pretty much like this:

I wake up with energy, new ideas, and focus. At the end of the day, I’m usually a little bit slower, less sharp. It’s pretty much a directly linear graph, with maybe a small bump from mid-morning caffeine.

Abusing drafts

Unfortunately, usually my PRs come as I’m wrapping up work for the day. I just get the urge to stop, commit, and then summarize where I left off, and often times a PR is a good way to do that.

These PRs usually come in ‘draft' status, with a big WIP label slapped on them, and usually some indication in the description that things are in-flight. This doesn’t stop the prying yet helpful eyes from making their way to this new implicit proposal for changes.

The result — my PRs inevitably end up being of better quality.

Side effects

Boo hoo, right? The downside here is twofold.

Time “wasted”

I end up wasting my co-workers time, as they have to spend time reviewing a PR multiple times. They also inevitably spot issues or opportunities that require comments / feedback, some of which might not have been there by the time they had their next morning’s coffee.

Impostor mode activated

Pushing a PR is implicitly exposing yourself to critique and constructive (hopefully) criticism. Other devs have to scrutinize the code you’ve written and evaluate it. This is naturally a vulnerable place to be for any dev.

By pushing branches and opening drafts before they’re fully ready, I expose myself to feedback on code that may (likely) not be my best work. Not always great for the confidence.

Getting better

I think my personal goal in writing this post was just to acknowledge a questionable dev habit. I think there are probably better ways to handle this, but I also think there is some merit to how I manage my PRs.

For example, I could probably be a bit more thoughtful about consulting my own ‘definition of ready’ when opening a PR. If it’s after 5 and you’ve just finished running the build with your latest fix to the point where it ‘works’ — it is actually okay to take a step back and just make a quick commit and leave it at that. Let ‘morning AJ’ get another crack at it before the rest of the team.

On the flip side, don’t be the dev that holds back PRs until the last possible second. Especially if your team relies heavily on them to communicate changes. Polishing code to a perfect sheen only to learn that you’ve missed something structural is the opposite danger here.

Anyway, thanks again to the folks who review my PRs. The little extra effort does not go unnoticed, and I appreciate the grace 😇

Hilt Navigation ViewModel is Perfect for Compose

Thu, 12 Jun 2025 00:00:00 GMT

If you've already got Hilt up and running, and you're willing to utilize the Navigation library for your Compose UI, the Hilt Navigation Compose library is a no brainer.

Essentially, what it allows you to do is get an Android Architecture ViewModel scoped to a navigation destination.

Here's my modified version of the example from the docs:

@Composable
fun MyApp() {
    val navController = rememberNavController()
    var startRoute by remember { mutableStateOf("example") }
    NavHost(navController, startDestination = startRoute) {
        composable("example") { backStackEntry ->
            val viewModel: MyViewModel = hiltViewModel()
            MyScreen(viewModel)
        }
    }
}

In this example you have a NavHost setup that you're using to navigate between screens. Inside your example destination, you use the hiltViewModel() function to get a ViewModel scoped to the destination that can then be passed into the MyScreen composable.

You may be wondering why this matters, as you could always use the viewModel() method to get a ViewModel in Compose. The key distinction here is scoping:

viewModel() returns an existing ViewModel or creates a new one. By default, the returned ViewModel is scoped to the enclosing activity, fragment or navigation destination, and is retained as long as the scope is alive.

If you're utilizing Compose Navigation, it just makes sense to be able to scope View Models to the nav destination, and further separate from a direct connection to Fragments or Activities.

Android view binding Easy Setup

Sun, 04 May 2025 00:00:00 GMT

Jetpack Compose is the way. But sometimes, you still need Fragments and XML. And if you have to deal with that, you'll probably want to use view binding. Writing this quick reminder for my future self for when I find myself in that predicament.

To enable view binding, add the following to your module build.gradle file:

android {
    ...
    buildFeatures {
        viewBinding = true
    }
}

This automatically generates a binding class for each layout. In my example activity_whatever.xml becomes ActivityWhateverBinding.

Then in your Activity (AppCompatActivity in this case) declare a lazy val for your binding and inflate it. Then setContentView to binding.root.

class WhateverActivity: AppCompatActivity() {
    private val binding: ActivityWhateverBinding by lazy { ActivityWhateverBinding.inflate(layoutInflater) }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(binding.root)
    }
}

This is a super quick & easy way to bind your XML. So simple that you'll avoid the urge to setup some base class just for making binding easier. If you were using a different Activity type, this also makes it easier to move to AppCompatActivity or ComponentActivity in the future to enable Hilt.

Create Your Own LOGAF Scale for Pull Request Reviews

Tue, 31 Oct 2023 00:00:00 GMT

I like the idea of the LOGAF scale, where we can easily indicate if suggestions to PR review or other feedback is given in 'levels of give-a-f*ck'. A scale like this helps collaborators prioritize and contextualize your feedback quickly in a way that's pretty straightforward.

While I love the raw LOGAF model, I do sometimes hesitate to share this philosophy with everyone at my company based on varying levels of comfort with profanity. Instead, I took the time just to indicate my own low/medium/high 'level of caring' that I can share on PR reviews. I also took the time to briefly spell out what I expect from each level. Now in PRs I can include a 'LOGAF level' link and move on.

Below is my basic scale of 3 levels, the description of each, and the link I'd include in each comment.

Low

A this level I usually just noticed something that had a slight code smell. I may spot things that are tangential to your change or just things I 'noticed' when reviewing.

You can self-resolve these comments in GitHub without a comment.

[🟢 low](https://ajkueterman.com/posts/making-your-own-logaf-scale-for-pull-requests/#low)

Medium

At this level I feel changes should be made but can be convinced with a good reason, a follow up story/documentation/etc. that captures the changes in future work or clarification.

You can self-resolve these comments in GitHub with a comment.

[🟡 medium](https://ajkueterman.com/posts/making-your-own-logaf-scale-for-pull-requests/#medium)

High

At this level I feel like changes need to be made before this PR is merged. In exceptional cases, follow up stories & documentation may resolve these concerns, but they would usually require a conversation with me or some other SME.

Do not self-resolve these comments in GitHub. Make changes / leave comments and allow me to resolve them before merging.

[🔴 high](https://ajkueterman.com/posts/making-your-own-logaf-scale-for-pull-requests/#high)

If you decide to implement your own LOGAF scale for your PR reviews let me know on Mastodon @aj on androiddev.social.

How to Use TalkBack on an Android Emulator

Wed, 26 Apr 2023 00:00:00 GMT

A huge part of making our apps accessible is enabling access for those who have limited vision. This can range from allowing users to adjust the size of the UI or the text in our apps - to making sure that accessibility tools like screen readers can parse the UI of our apps.

The screen reading tool provided by Google on Android devices is called TalkBack. This app is usually installed by default on Android devices, letting users operate their phones without needing to see the screen. For developers, we can use TalkBack to ensure our app is accessible.

However, you may have noticed that this behavior isn't available by default when you create a new Android Emulator in Android Studio - a problem for developers & testers that don't have access to physical devices.

Let's walk through the process of getting TalkBack set up on your Android Emulators.

Create A New Emulator

In Android Studio (I'm using Android Studio Flamingo 2022.2.1), open the Device Manager and choose Create Device.

Select Hardware

Select a device you'd like to create an Emulator of, making sure to select one that has Play Store access. You can tell by the Play Store icon visible in the 'Play Store' column of the selection list.

After selecting the appropriate hardware, click Next.

System Image

Select or download an Android OS image. I chose to download & select Android Tiramisu (API 33), though any modern OS will do.

Once that is downloaded & selected, click Next.

AVD Setup

We've done all the hard work, no changes needed here unless you need to make specific adjustments to your Emulator setup. Click Finish.

Download the Android Accessibility Suite

Back in Device Manager, click the 'play' button on your newly added device to run it.

If, at this point, we decided to go into Settings and look for TalkBack, we won't get any results. This is the default behavior for all new emulators you create. Let's fix that by downloading the Android Accessibility Suite.

Sign In & Search

Your device should have the Play Store app already installed. Open it, and sign in with your Google account. You may have to go through a few setup steps when logging in to the Play Store, as this emulator is treated as a 'new' device.

In the Play Store search for 'android accessibility suite' and download it.

Using TalkBack

After it downloads and installs, close the Play Store and look at your list of installed apps. You may notice that the Accessibility Suite doesn't show up here. That's expected for this very specific app.

Instead, open Settings, and search for TalkBack. Here you'll see the TalkBack option, which brings you to the Screen Reader section of the device's Accessibility settings.

Ta-da! 🥳 Now we can use TalkBack just like we would on a normal Android device.

TalkBack Resources

For more on testing your apps for accessibility with TalkBack, check out these great resources:

Go forth and build accessible apps!

Visualizing Data with Swift Charts

Tue, 11 Apr 2023 00:00:00 GMT

This is a re-post of the article I shared @ the Base11 Studios blog.

Now, with Swift Charts we can easily make that a reality in our apps. Take, for example, a basic Line Chart like the one used in CaliCalo to display a user's Diet vs. Active calorie count over seven days.

With this screen, we want to communicate essential but pivotal data quickly. How have you been balancing your NET calories (calories consumed vs. calories burned) for the last seven days? We plot two lines - one for calories consumed (diet) and one for calories burned by daily totals.

By quickly scanning the graph, users can see how their lines overlap. Depending on their goals, this can help inform progress.

For a user trying to maintain weight, the goal may be to have the lines match up as closely as possible.
A user trying to lose weight would be trying to consistently keep the 'Diet' line below the 'Burned' line. Opposite for the user trying to gain weight.

For either user, the line graph can help identify significant disparities or inconsistencies that can help guide behavior or tracking.

Swift Charts

Apple's Swift Charts library offers a quick and easy way to start plotting data. We'll use this library, along with SwiftUI, to build out our Trends chart.

Brief Overview

A quick explainer of Swift Charts in the world of SwiftUI. You have a Chart view that takes a body that should be a list of 'marks.' Marks can be things like BarMark, LineMark, or PointMark that plot out the data depending on the type of chart you're making.

Add to this Chart (and its marks) some modifier functions that allow us to declare how our data dimensions are displayed & styled, and we have a pretty chart showing data at a glance.

Make a Mark

Let's look at a straightforward example. Here, we're charting calories per day using some brute force. Let's create a Chart with some LineMarks.

import SwiftUI
import Charts

struct SimpleLineChartView: View {
    var body: some View {
        VStack {
            Chart {
                LineMark(
                    x: .value("Day", Calendar.current.date(from: .init(year: 2023, month: 1, day: 1)) ?? Date()),
                    y: .value("Calories", 2000.0)
                )
                LineMark(
                    x: .value("Day", Calendar.current.date(from: .init(year: 2023, month: 1, day: 2)) ?? Date()),
                    y: .value("Calories", 1800.0)
                )
                LineMark(
                    x: .value("Day", Calendar.current.date(from: .init(year: 2023, month: 1, day: 3)) ?? Date()),
                    y: .value("Calories", 2300.0)
                )
            }
        }
    }
}

The code above results in a simple, practical-looking chart that plots our 3 points on a line.

Cool to see some data visualized! Let's look at a slightly more complicated example, where we map two lines. This time, we're plotting the two types of calories we care about in CaliCalo - Diet and Burned. To do this, we need to plot 2 points for every day.

If we were to add a bunch of points (manually like in our example above or by looping over some data), we'd end up with a chart that looks something like what you see below—one long continuous line on the chart zigging back and forth.

Technically, all the data has been charted, but visually we aren't differentiating between the type of data supplied to the Chart. I think we should do that next.

Add a Modifier

Swift Charts uses modifier functions to add dimensions to how the data is displayed. It can help separate data sets and display them using different colors/shapes/curves etc. The first one we'll utilize is foregroundStyle(by:), which we can use to change how we display our data set.

Let's do a little prep first to make our Chart function a bit easier to read (and make it a more realistic example).

First, let's create some structs to represent data points for our calorie data.

struct Diet {
    let dateLabel: String = "Day"
    let date: Date
    let valueLabel: String = "Diet"
    let value: Double
}

struct Burned {
    let dateLabel: String = "Day"
    let date: Date
    let valueLabel: String = "Burned"
    let value: Double
}

Then, let's create some test data. We'll create a list of Diet objects we can use to populate the chart for a 5-day period.

let diet: [Diet] = [
    Diet(
        date: Calendar.current.date(
            from: .init(
                year: 2023,
                month: 1,
                day: 1
            )
        ) ?? Date(),
        value: 2000.0
    ),
    Diet(
        date: Calendar.current.date(
            from: .init(
                year: 2023,
                month: 1,
                day: 2
            )
        ) ?? Date(),
        value: 1800.0
    ),
    Diet(
        date: Calendar.current.date(
            from: .init(
                year: 2023,
                month: 1,
                day: 3
            )
        ) ?? Date(),
        value: 2300.0
    ),
    Diet(
        date: Calendar.current.date(
            from: .init(
                year: 2023,
                month: 1,
                day: 4
            )
        ) ?? Date(),
        value: 2100.0
    ),
    Diet(
        date: Calendar.current.date(
            from: .init(
                year: 2023,
                month: 1,
                day: 5
            )
        ) ?? Date(),
        value: 1500.0
    ),
]

In the following snippet, we'll use this same list twice to map two lines, but in a real example, we would have two separate lists of test data that we would chart in the next step.

Using this list of data, we can now chart two lines. We'll use the foregroundStyle(by:) function to define each LineMark's style for each item in the list. It's a way of indicating how to display a given mark.

struct SimpleLineChartView: View {
    var body: some View {
        VStack {
            Chart {
                ForEach(diet, id: \.date){ dataPoint in
                    // 'Burned' Calorie data, from our list of `Diet` objects
                    LineMark(x: .value(dataPoint.dateLabel, dataPoint.date), y: .value(dataPoint.valueLabel, dataPoint.value))
                        .foregroundStyle(by: .value("BURNED", "BURNED"))
                    // 'Diet' Calorie data, also from our list of `Diet` objects, but shifted by -300 calories
                    LineMark(x: .value(dataPoint.dateLabel, dataPoint.date), y: .value(dataPoint.valueLabel, (dataPoint.value - 300.0)))
                        .foregroundStyle(by: .value("DIET", "DIET"))
                }
            }
        }
    }
}

We'll get a chart that looks like this without any extra setup.

A line chart with two lines of five points each (using our diet array x2). We even have a cute little legend at the bottom left indicating what the lines mean by color.

Add some Style

Green and blue are just the API's default colors without us doing any extra work. If we want to add some of our special branding sauce, we use another simple modifier. On the Chart, we can apply the .chartForegroundStyleScale(_:) modifier to define the colors we want to use for each of our data sets.

Chart {
    /// ...
}
.chartForegroundStyleScale(["DIET": Color.orange, "BURNED": Color.blue])

With only that 1 line, we've got some nice CaliCalo colors:

Modifiers by Example

Now that we understand some of the basic building blocks of Swift Charts let's look at a few more ways to modify our chart style. Ultimately, we should have a chart that looks close to what we've built for CaliCalo.

Chart Modifiers

These modifiers are applied to the Chart view.

Modifier	Description	Example
`.chartXScale(range:)`	Add 20 pts. of padding to the X axis.
`.chartXAxis(content:)`	Use `AxisMarks` to remove Y axis lines.
`.chartPlotStyle(content:)`	Set the height of the chart contents within the Chart view.
`.chartYAxis(content:)`	Move Y Axis labels to leading edge.

LineMarks Modifiers

We can apply some additional modifiers to the LineMarks to improve the overall look and feel of our Chart lines.

Modifier	Description	Example
`.interpolationMethod(_:)`	Set `.catmullRom` as the interpolation method.
`.symbol(_:)`	Set `.square` and `.circle` as the line mark symbols.

Modifiers Combined

Here's how those modifiers are provided to the Chart and Marks to make the last chart example.

//...
Chart {
    ForEach(diet, id: \.date){ dataPoint in
        LineMark(x: .value(dataPoint.dateLabel, dataPoint.date), y: .value(dataPoint.valueLabel, dataPoint.value))
            .foregroundStyle(by: .value("BURNED", "BURNED"))
            .interpolationMethod(.catmullRom)
            .symbol(.square)
        LineMark(x: .value(dataPoint.dateLabel, dataPoint.date), y: .value(dataPoint.valueLabel, (dataPoint.value - 300.0)))
            .foregroundStyle(by: .value("DIET", "DIET"))
            .interpolationMethod(.catmullRom)
            .symbol(.circle)
    }
}
.chartForegroundStyleScale(["DIET": Color.orange, "BURNED": Color.blue])
.chartXScale(range: .plotDimension(padding: 20.0))
.chartXAxis{
    AxisMarks(preset: .aligned, position: .top, values: .stride(by: .day)){ value in
        AxisValueLabel(format: .dateTime.day().weekday(.narrow))
    }
}
.chartPlotStyle{plotArea in
    plotArea.frame(maxWidth: .infinity, minHeight: 250.0, maxHeight: 250.0)
}
.chartYAxis{
    AxisMarks(position: .leading)
}
//...

Wrapping Up 🎁

Combined, we can design a chart that closely mirrors our CaliCalo Trends UI.

Our Example	Trends UI

We also learned about the basic building blocks of Swift Charts and how easily modifiers can be applied to make Charts our own.

For the complete source of this example, plus a more complex example that includes some randomized test-data-generation, check out our Trends Chart Repo on GitHub.

🐘 If you liked this article and want more tech content (and other nerd commentary) you can follow me on Mastodon. I hang out at AndroidDev.social @aj.

Make 'Dragon Heist' Your Own

Sun, 20 Jun 2021 00:00:00 GMT

Waterdeep: Dragon Heist is one of the most exciting adventure modules for D&D 5e, dropping your Level 1 adventuring party into the heart of the 'City of Splendors'. But how can you take this dense urban caper and make it your own?

Waterdeep is one of the most well known cities in the Forgotten Realms, positively brimming with adventure and backed up with heaps and heaps of lore. In the book there is an entire appendix - "Volo’s Waterdeep Enchiridion" - which introduces the DM and adventurers to the city in a crash course that covers history, locations and getting around, and special events & points of interest.

All of this is extremely helpful to those new to Waterdeep, while simultaneously being completely overwhelming. Not only do you have to try to internalize some of this lore to have it ready at the table when you offer the occasional History check, but you probably also want to try to populate Waterdeep in a way that makes it feel as big as it's described when your players are moving around the world.

Here are my tips for running Waterdeep: Dragon Heist, along with the most useful sources & supplements I've gone to along the way.

Buy the Right Sources

Before you can get started running your game, you need to acquire the right materials. But before you start shelling out that cold hard cash, you need to consider the game you plan to run.

If you're running the game in-person, then the adventure book is indispensible. Having that reference on-hand during the game is super useful. In my experience quickly flipping through the pages of the adventure book is much more effective even than swapping tabs and searching the text of a digital book.

If you're running the game remotely, then the physical book is a luxury, not a necessity. Instead, you need to decide on one or more digital versions of the module. Your two options are:

Buy the adventure on Roll20 or your favorite VTT (Virtual Tabletop) of choice.
Purchase the adventure source on D&D Beyond.

Roll20 (or VTT)

In general, I would strongly suggest buying the VTT version of the adventure. On Roll20, purchasing the adventure gives you access to the entire text of the adventure plus:

All of the maps included in the adventure, pre-built with the proper size, layers, and dynamic lighting.
All of the key NPC's, monsters, and other tokens populated in the VTT with character sheets & abilities.
The adventure structure broken out by season, so you get only the versions of the map you need, pre-populated with the correct monster tokens & lighting.

These features add up to hours of prep time saved, meaning you have much more time to focus on the story you want to tell, or by enhancing your Roll20 game with additional maps & characters.

D&D Beyond

So if you've already decided to pick up the Roll20 Marketplace version for your remote game, or the physical book for your in-person game - then why would you turn to D&D Beyond?

The primary reason the D&D Beyond sources are valuable, is it opens up the possibility of sharing some content with your campaign. For certain campaigns, this can mean unique character backgrounds that let players customize their characters to this specific adventure.

In the case of Waterdeep: Dragon Heist, there aren't unique backgrounds to this adventure. There are, however, especially relevant backgrounds in the Sword Coast Adventurer's Guide:

Players looking for background options beyond those described in the Player’s Handbook can find several appropriate ones in the Sword Coast Adventurer’s Guide: City Watch, cloistered scholar, courtier, faction agent, far traveler, inheritor, mercenary veteran, urban bounty hunter, and Waterdavian noble. If you have access to this book, consider making its background options available to your players’ characters.

So if you can avoid spending the extra dragons on the D&D Beyond source, it may be more worthwhile to invest in the Sword Coast Adventurer's Guide, which will give you much more background and context relevant to the region and also give you those extra backgrounds.

Waterdeep: City Encounters

So you unfurl the poster map of Waterdeep to see the insane level of detail in this city and your brain is probably reeling as you imagine what to fill it with. You may have some ideas for a spare NPC or side quest, but figuring out hooks for this whole world is a daunting task.

Enter Waterdeep: City Encounters, an amazing supplement for any Waterdeep-based campaign or Sword Coast adventure that includes the City of Splendors. Brought to you by an amazing team of authors & Guild Adepts on the Dungeon Masters Guild, this supplement offers over 100 encounters that are set throughout the city.

The module offers two flavors of encounters - a table of random encounters that change based on what ward your characters are currently exploring, and a dense set of location-based encounters.

This design means you can sprinkle random encounters throughout your campaign no matter where your characters are in the city, spicing up any possibly dull moments or just giving your players a sense of life happening in the background within the walls of Waterdeep. With the location-based encounters, you can make the city's points of interest really stand out and be memorable to your players, or offer an opportunity to draw them into a larger plot or side quest.

If you're worried about the encounters being too brief - the module offers a good balance. Some encounters are complete one-offs, but others connect to one another, and can unfurl larger plots that connect locations throughout the city. Some encounters also pull in notable Waterdavian characters that are also involved in Dragon Heist, offering opportunities to weave the two narratives together.

Overall, I think Waterdeep: City Encounters is a must-have supplement to Dragon Heist, or any Sword Coast-based adventure that might draw your characters here.

Blue Alley

This adventure can be seen as a prologue to the epic dungeon crawl that is Waterdeep: Dungeon of the Mad Mage. Despite that, Dragon Heist is actually somewhat light on dungeon-crawling. The structure is a bit more encounter-based, allowing your characters to explore and bounce around as they unfurl the plot.

So if you're looking for a way to spice up the side-quests for your characters and offer some extremely solid dungeon-crawling, you need to pick up Blue Alley on the DM's Guild.

In Blue Alley, your adventurers are tempted with gold & glory by none other than Mirt - offering you an easy hook into Dragon Heist, especially if your characters have forged a connection with The Harpers. The dungeon offers an array of traps, puzzles, monsters, and treasures to unfold. It is unique and varied in its challenges, and should offer possibilities for further side-quest hooks if you want to get creative.

Blue Alley Map

If you want to spice up your dungeon-dive with some amazing improved maps, I also highly recommend the Blue Alley Map supplement as well. They are complete with beautiful lighting & improved assets to help spruce up your VTT version of the game.

Maps

If you're running the game in-person, a grid board and wet erase markers are your absolute best friend. However if you're running the game on a virtual table top and are looking for ways to expand on the maps included in the adventure, check out a few of these excellent mapping resources.

Dyson Logos

The sole map illustrator for Dragon Heist is Dyson Logos - a legendary RPG map-maker with hundreds of free maps and many more resources for patrons, plus full books of maps for sale online.

If you're interested in expanding on the existing maps in this module, his website is a great resource for random battle maps and maps to inspire fun side quests or mini-dungeons. A few sections on his website highlight some especially useful categories, including Inns and Taverns and Sewers, that blend easily into the urban setting.

Cze and Peku Maps

Another great D&D map-making site, Cze and Peku make beautiful maps for all sorts of games. From the Astral Sea to an encounter with an Elder being to a lovely day by the lake shore, they have drawn a map for any situation.

Simply searching by the 'city' keyword brings up dozens of amazing maps that would slot easily into Dragon Heist. And at ~$5 a map they can be an affordable way to expand your version of Waterdeep and add that level of immersion we're all searching for.

Dice Grimorium

If you're looking for a bank of free, full-color battle maps to have at the ready for any encounter, the Dice Grimorium free catalog is just that.

George works to create a new map each week, most of which he amazingly shares for free on his site and social media. In addition you can support him on Patreon and get additional tokens for each map (perfect for your VTT) and even the original PSD files in case you have map-customization aspirations.

Closing Thoughts

As a DM, you can never do enough preparation. I hope this guide has helped give you some resources, ideas, or inspiration for your next adventure to the City of Splendors. Don't let this beautiful gem of the Sword Coast intimidate you, and make it into what you want.

As always, the act of DM'ing is more an art than a science. Remember to improvise. Remember to let your players lead. And remember to have fun!

Good luck out there! If you have thoughts, feedback, or suggestions for future posts - let me know on Mastodon.

Use Good Tools

Tue, 27 Apr 2021 00:00:00 GMT

I recently finished reading Blood, Sweat, and Pixels by Jason Schreier, a book that goes behind the scenes on the making of several popular video games released in the last decade. The book was an awesome look at the drama inherent in a massive creative endeavor like making games or movies, and it had some interesting parallels to other fields - including software development.

One of my favorite quotes in the book was specifically insightful, and relatable from my experience writing applications. When discussing the writing of the engine & tooling behind Destiny, one developer said:

"The biggest differentiator between a studio that creates a really high quality game and a studio that doesn't isn't the quality of the team, it's their dev tools. If you can take 50 shots on goal and you're a pretty shitty hockey player, and I can only take 3 shots on goal and I'm Wayne fucking Gretzky, you're probably going to do better. That's what tools are. It's how fast can you iterate."

I immediately flashed back to all the dev tools I've worked with over the years. How something like moving from Eclipse to Android Studio completely changed the Android Dev experience and made it accessible in a way it wasn't before. I thought about some of the rockstar devs I worked with who moved mountains to ship good code with bad tools. While that was impressive it hid the fact that, given good tools, maybe everyone on the team could have been putting out similar work.

Invest in good dev tools. Listen to new people who join the team and have complaints about the way that you work. Building or buying better dev tools is a more sustainable way to get more good work out there, because it doesn't rely on only the "best", most technical people to make your teams successful.

Sure, we want devs who can overcome hurdles. But if you rely on only hiring the devs who can survive your bad dev pipeline to ship code, you're going to have a lot of people not shipping, because they're stuck helping other devs learn to ship within a broken process.

Instead of expecting people to reach a certain height to survive and ship good code, raise the floor.

Android ViewModel - Manual Dependency Injection Made Easy

Mon, 28 Sep 2020 00:00:00 GMT

The Android team has been increasingly vocal about their support for Dependency Injection frameworks like Dagger, going so far as to develop and recommend Hilt - their Android DI framework built on top of Dagger - for modern Android development.

In their guide to manual dependency injection the Android team lays out approaches to manual DI for View Models. They offer both the basic approach to manual DI - just instantiating everything you need in onCreate and using lateinit var View Models - and the container approach using a custom AppContainer to handle dependencies across all your Activities.

The alternative they give to this boiler-plate-heavy approach is to recommend Dagger or Hilt to handle this process for you. However, in many apps, pulling in a DI framework is overhead you really don't need. Instead, what if there was a way to manually inject dependencies into your Android Activity & Fragment View Models without all the boiler plate?

Lazy DI Using Android Lifecycle ViewModel Extensions

One of the ways the Android Fragment & Lifecycle teams have tried to make the View Model easier to use in Activities and Fragments is providing the Android Lifecycle ViewModel Kotlin Extensions library.

dependencies { 
    implementation "androidx.lifecycle:lifecycle-viewmodel-ktx:2.2.0"
}

This library lets you instantiate a View Model in a Fragment or Activity with a delegate method - making it easy to create a properly scoped View Model.

class MyActivity : AppCompatActivity() {

    private val model: MyViewModel by viewModels()

    override fun onCreate(savedInstanceState: Bundle?) {
        model.getUsers().observe(this, Observer<List<User>>{ users ->
            // update UI
        })
    }
}

This is beautiful! However, what if our View Model needs to use a repository to make a call to Retrofit? We would like to inject that repository into our View Model when we construct it.

View Model Provider Factory

One way to enable this behavior is to use ViewModelProvider.Factory, with which you can instantiate a View Model with it's needed dependencies. To do so, you need to create your own Factory that extends the ViewModelProvider.Factory interface, or create a function that can return an object that overrides the Factory.create method.

If we wanted to stop here, we could create a Kotlin function to do this for us:

fun createWithFactory(
  create: () -> ViewModel
  ): ViewModelProvider.Factory {
    return object : ViewModelProvider.Factory {
        override fun <T : ViewModel?> create(modelClass: Class<T>): T {
            @Suppress("UNCHECKED_CAST")// Casting T as ViewModel
            return create.invoke() as T
        }
    }
}

And use it in our Activity or Fragment like this:

private val model: MyViewModel by lazy {
  ViewModelProvider(
    this, 
    createWithFactory {
        MyViewModel(repo = MyRepository())
    }
  ).get(MyViewModel::class.java)
}

We can now create a View Model with the necessary dependencies! However, even with our Factory abstracted into a function, we still need to manage the boiler plate of ViewModelProvider.

View Model Provider & Kotlin Extension Mashup

Remember, we could use by viewModels or by activityViewModels to delegate the creation of our View Models, but we weren't able to inject our required dependencies without a Factory.

Now that we have a handy way to instantiate a View Model with a Factory, we can let these Kotlin Extensions for View Model to hide this ViewModelProvider boiler plate. Here's how it would look in a Fragment.

private val model: MyViewModel by activityViewModels {
    createWithFactory {
        MyViewModel(repo = MyRepository())
    }
}

Almost perfect. All we have to do is provide a Factory and a lambda that returns our View Model. But, with a little help from the lifecycle-viewmodel-ktx library and Kotlin extension functions, we can take it one step further.

Endgame: Easy View Model DI

Let's use the power of extension functions, our Factory knowledge, and the ViewModelLazy class to delegate the creation of our View Model to functions on Activity and Fragment.

We provide the function to create our View Model as a lambda that returns type <VM : ViewModel>, and the viewModelBuilder and activityViewModelBuilder extensions do the rest.

/**
 * Get a [ViewModel] in an [ComponentActivity].
 */
@MainThread
inline fun <reified VM : ViewModel> ComponentActivity.viewModelBuilder(
    noinline viewModelInitializer: () -> VM
): Lazy<VM> {
    return ViewModelLazy(
        viewModelClass = VM::class,
        storeProducer = { viewModelStore },
        factoryProducer = {
            return@ViewModelLazy object : ViewModelProvider.Factory {
                override fun <T : ViewModel?> create(modelClass: Class<T>): T {
                    @Suppress("UNCHECKED_CAST")// Casting T as ViewModel
                    return viewModelInitializer.invoke() as T
                }
            }
        }
    )
}

/**
 * Get a [ViewModel] in a [Fragment].
 */
@MainThread
inline fun <reified VM : ViewModel> Fragment.activityViewModelBuilder(
    noinline viewModelInitializer: () -> VM
): Lazy<VM> {
    return ViewModelLazy(
        viewModelClass = VM::class,
        storeProducer = { requireActivity().viewModelStore },
        factoryProducer = {
            object : ViewModelProvider.Factory {
                override fun <T : ViewModel?> create(modelClass: Class<T>): T {
                    @Suppress("UNCHECKED_CAST")// Casting T as ViewModel
                    return viewModelInitializer.invoke() as T
                }
            }
        }
    )
}

Now, in our Activity:

private val model: MyViewModel by viewModelBuilder {
    MyViewModel(repo = MyRepository())  
}

Or Fragment:

private val model: MyViewModel by activityViewModelBuilder {
    MyViewModel(repo = MyRepository())  
}

We can easily build a ViewModel, along with all it's necessary dependencies, all without the annoying boilerplate!

If you're in a situation where you need complex Android View Models, want to follow SOLID principles of dependency injection, and you're not quite ready to adopt the complexity of a full Dependency Injection Framework - hopefully this helps present some other options that can make the task easier to manage.

If you have thoughts on the Android View Model or want to share your approaches to manual DI, don't hesitate to reach out on Mastodon, or follow me on DEV.to.

Library

If you just want to import and go, check out the Lazy ViewModels library on GitHub.

Lean Software Estimation

Wed, 09 Sep 2020 00:00:00 GMT

Estimation is one of the hardest problems in software development. Trying to calculate the time required to solve complex technical and organizational problems is more magic than art. As Kelly Vaughn on Twitter put it...

When you give a developer 5 hours for a task, they'll let you know they need 50 hours once they've used up 10.

Even looking at the most atomic of these calculations - estimating an engineering task or user story - it's clear to see that estimations are no exact science. We engineers size stories based on technical complexity, but even that is no exact correlation to time spent, as there are countless variables to this measure - skillset, experience, motivation, relationships - just to name a few.

Now multiply that complexity by the number tasks or user stories required to make up a feature. Consider how those variables expand beyond one developer to a team, or group of teams as the complexity of the compounded problems build on each other. As features combine to form epics, and epics may be combined to form a product release, we start to spiral out of control.

Just as a 1 point story means something completely different team-to-team, the same is true of user story comparison or epic comparison. Estimates on this order of magnitude are practically meaningless, as even the most seasoned teams are only just estimating - and on a much smaller scale. Remember the tweet: 5 could be 50 when you're standing in front of a pile of work. 5 months becomes 4 years.

Excellent advice could be to shut up and plan the sprint, remembering that our agile frameworks like Lean teach us to make decisions late and focus on the most important things first. As an engineer, I know that is usually the right thing to do to be as efficient as possible. On the other hand, I'm offloading a lot of the mental energy that it takes to decide "what's next" to our product teams.

And in product, the eternal struggle is understanding how to plan. How to determine how to spend money and trying to calculate when investments are going to pay off. So the conversation turns to asking for commitments, and 2 weeks isn't a very long time.

I fear the answer includes some nuance, but a few things I think you'll need first.

Trust (and investment) in your dev teams
Enable incremental improvement, and ask for proof
Change as a result of tangible output, not perceived progress

Trust (and Invest) in Your Dev Teams

The entire agile philosophy is built on the idea of high-performing teams. If you go into the process doubting that your dev team is performing at their best, or that they're not up to the task, the structure immediately begins to break down. When you don't trust a developer's estimate to be the truth - and instead some fake number meant to inflate the work or buy time - you've failed.

Even in the real scenario where your dev team isn't so high-performing, trusting their work, estimates, and convictions is critical to the process.

To continue to build this trust, engineering teams should be invested in and empowered. It's the goal of the engineering leadership to find, cultivate, and empower great engineers. They should be experts at helping engineers reach their high-performing potential, and clear-eyed about areas to be improved. The culture in the engineering organization should be one that reinforces leadership and learning. Good engineers should be rewarded.

Enable Incremental Improvement, and Ask For Proof

The faster the product is in your hands, the faster you can start to learn. An unreleased product is a net drain on resources, whereas any code in production provides value to users and teams.

This means that moving a product from development to production is more important than how much value you're providing per-release. Focus less on understanding the path to deliver on an entire feature or feature-set, and more on how you can start to iterate on the smallest changes possible. Let product ideas evolve instead of trying to decide on perfect early.

Working software is preferred over planning. Meaning your team should be focused on building. Each sprint, or faster, your engineering team will deliver software that can be demonstrated. Asking for real work to be demonstrated is a cornerstone of the process. Focus less on the scope of work and more on the fact that work can be delivered every sprint.

Change, as a Result of Output

The concept of deciding late can be foreign to project teams used to slow, huge, disruptive releases. It's scary to "let go and let Lean" when we aren't used to seeing real code go fast.

In a productive team, you should get used to letting things go to users un-polished, and learn how to react quickly to feedback. Try to resist the urge to change direction before getting feedback from users.

Back to Kelly's tweet - you aren't going to be able to avoid engineers finding work that needs to be done. The point of the tweet is to focus on not putting too much time, effort, and value in zeroing in on a 5-hour estimate for something we don't understand yet.

Instead, let engineers invest that planning time in writing real code. Let them learn from the code they do write. Let them get that code to production - fast! And then, change based on the code in users' hands.

Safely Launch Exception-Ready Coroutines

Wed, 11 Mar 2020 00:00:00 GMT

Launching suspend functions in Kotlin can be a complicated affair. Managing your CoroutineScope and making sure exceptions are handled properly can be confusing and easy to forget.

In Android, when using the ViewModel or Lifecycle specific scopes this gets much easier. We let the Android system provide a CoroutineScope and manage killing our coroutines when the lifecycle of those things end.

fun getObjectFromNetwork() {
  viewModelScope.launch {
    val response = networkRepository.getObject()
  }
}

However, there are cases when exceptions can be thrown from the CoroutineScope. A real life example I experienced recently was a SocketTimeoutException that was thrown from a Retrofit call I was making using a suspend function. The result is an Android app crash, which is definitely not desired when network calls can result in many different thrown exceptions.

The Kotlin CoroutineExceptionHandler can help us more easily handle exceptions thrown from our Coroutine scope, but it requires us to register the exception handler when we launch a new coroutine so we properly handle nested exceptions.

val coroutineExceptionHandler = CoroutineExceptionHandler { coroutineContext, throwable ->
  // handle thrown exceptions from coroutine scope
  throwable.printStackTrace()
}

fun getObjectFromNetwork() {
  viewModelScope.launch(coroutineExceptionHandler) {
    val response = networkRepository.getObject()
  }
}

Now, while the ViewModel is probably a logical place for handling exceptions in network calls, there are a lot of exceptions that are thrown irregularly from your app that aren't part of the logical flow of a network call. Using Retrofit as an example, most network calls should return a Response with a body() or errorBody() to handle instead of edge-cases where actual exceptions, like a SocketTimeoutException is thrown. It might be worth it to you to abstract this error handling away from your ViewModel to help minimize boiler plate.

To try this out, let's leverage the power of Kotlin extensions to create a safeLaunch method on CoroutineScope that can apply a default CoroutineExceptionHandler.

fun CoroutineScope.safeLaunch(launchBody: suspend () -> Unit): Job {
  val coroutineExceptionHandler = CoroutineExceptionHandler { 
  coroutineContext, throwable ->
    // handle thrown exceptions from coroutine scope
    throwable.printStackTrace()
  }
  
  return this.launch(coroutineExceptionHandler) { 
    launchBody.invoke() 
  }
}

Now, we can call safeLaunch on any CoroutineScope, like our viewModelScope, to launch a coroutine with this default error handling behavior.

fun getObjectFromNetwork() {
  viewModelScope.safeLaunch {
    val response = networkRepository.getObject()
  }
}

There you have it! A nicely-encapsulated method to launch suspend functions knowing that we won't see random app crashes because of an unhandled Throwable.

If we wanted safeLaunch to be the core CoroutineScope launch method in our app, we can even improve the extension a bit to allow users the flexibility of passing their own CoroutineExceptionHandler instead of using the default.

val coroutineExceptionHandler = CoroutineExceptionHandler { coroutineContext, throwable ->   
  throwable.printStackTrace()
}

fun CoroutineScope.safeLaunch(
  exceptionHandler: CoroutineExceptionHandler = coroutineExceptionHandler,
  launchBody: suspend () -> Unit
): Job {  
  return this.launch(exceptionHandler) { 
    launchBody.invoke() 
  }
}

The same day I wrote this article, Manuel Vivo and Florina Muntenescu from the Android developer relations team released a really good series on coroutines, including the subject of coroutine exceptions. Check it out if you want to learn more about coroutines and how to manage them.

What Works at Work

Sun, 19 Jan 2020 00:00:00 GMT

A list of things that have worked better for me at work than other things.

Worked	Did Not
Working in a shared space with my team worked.	Being in an open office or in cubicles/offices did not.
Working on sticky notes and whiteboards worked.	Using a complex digital tool did not.
Working all on-site together or all distributed worked.	Working with portions of the team remotely did not.
Enabling developer collaboration worked.	Forcing people to collaborate did not.
Enabling pair programming worked.	Forcing people to pair on everything did not.
Testing users to understand the problem worked.	Assuming the problem or testing for the sake of testing did not.
Working on small iterations of code worked.	Thousand-line pull requests did not.

A 2019 Freelance Year-in-Review

Fri, 03 Jan 2020 00:00:00 GMT

2019 was an exciting year for me professionally, both in my career as an Android developer with Fifth Third Digital and also in my work with Base11 Studios. It is the first year I've ever actually made a profit on doing freelance development work, and it was an exciting ride with a lot of lessons learned along the way. As 2019 comes to a close I wanted to take a minute just to share my experience and expand on some of those details.

Base11 Studios is a business owned by two of my closest colleagues in the Cincinnati development scene, Ryan Klein and Dan Bellinski. Over the last two years I've worked with them to help expand our catalogue of Base11 apps, both by writing code for Ryan & Dan projects and by building my own apps to release under Base11 Studios. As 2018 grew to a close last year - a busy year in which I launched both fuzZzy and OctoNote on the App Store and built Fit Foods Coach for Android - we got comissioned to build a POC and later a full product on a scale unlike any previous Base11 Studios endeavor.

So the story of 2019 is basically how I learned to deal with rapidly building a fully featured iOS app for clients, how that is different than building apps for yourself, how partnerships work in real life, and how you have to make hard choices when working in your free time - among other things.

From POC to Prod

In late 2018 and Dan, Ryan, and I worked on a POC prototype app to prove out image processing on iOS with an AWS back-end to detect specific types of documents. The focus was on capturing, processing, and predicting golf scores based on different types of scorecards.

We had an amazing experience in this first leg of the journey. I learned a ton about iOS's Machine Learning and Vision API's and had the opportunity to put them into practice in a practical sense. Dan and Ryan built some real IP on the back end processing of scorecards and learned a ton about AWS, and specifically AWS products and strategy at our scale.

At the end, we showed our clients our POC app and what we learned, and they decided they wanted to move forward with us to build out a production-ready version of our core feature set - scanning a golf scorecard and automatically detecting and calculating a handwritten score. Still minute in the types of startup dollars you hear about - this would be our biggest financial deal to date. The deal was structured as monthly payments to the LLC to build the prod-ready MVP app with a goal delivery date, at which time we'd negotiate our partnership.

Building Fast

In this first sprint we worked from January until early May on delivering our prod-ready MVP. This was an exciting time filled with a lot of coding in my free time. I took a deep dive on the Vision API's I implemented in the prototype and completely rewrote the core scanning code to be performant. I built out the image manipulation portion of the code to re-shape images to the correct perspective based on camera/scorecard angle at capture. I overhauled and re-designed the entire UI, and implemented some inventive UI patterns to seamlessly work the user through the scanning, capture, and correction flow.

At the end, the three of us were completely wiped, but excited with all that we had learned and built. We presented our MVP to our clients, who were extremely excited to move forward to release. We gave them a TestFlight build of the iOS app and a sandbox IST environment to test on, and planned to meet up to plan our rollout.

Goal Alignment

A big lesson from this first MVP handover was one of expectation and goal alignment. When we met with our clients to demo our MVP, we were 99% of the way to clicking the release-to-prod button in App Store Connect with our simple but production-ready app. To them, while they might have agreed on the production ready portion, they weren't ready to release our simplified effort to the wild world.

After testing our app in the real world, and running into inevitable problems with image capture in a real-life environment, they were not ready to commit to a prod release. While I had already made big improvements in image capture between our MVP reveal and next meeting, they seemed to have other fundamental problems with the scope of our first MVP.

So, after this first false start, we continued to work on tweaking and improving our MVP in our lead-up to an official meeting to plan our next few months of building towards their vision for an initial release.

Own Your Work

The meeting turned out to be one that defined our experience building this app, and tought us a hard lesson about owning our own IP in any project we built moving forward.

Before we met, Dan, Ryan, Cory - our business lead, and I all agreed that we were ready to work to bring this fully-featured app to production as partners with our clients. We had worked really hard on our core feature set, but understanding the effort ahead after this recalibration and seeing how much of our IP we were essentially giving away for free, we wanted to make sure we had some ownership of the project in the next phase. We came into this meeting with the goal to understand what our equity stake would be in this project/company and discuss what we would build and by when.

Our clients had done similar thinking, but of course had a different perspective on ownership. In their minds, we had taken their money to build and in doing so had voided our claim to equity. Why should they give us stake now, after already investing so much in this product - a product that they had already paid for? We didn't disagree on the fact that we were paid, but we were staking our equity claim on our IP expertise and what we were about to deliver for them to finalize their fully-featured first release. To them, this calculation didn't work out, and weren't willing to meet us anywhere close to our equity goals.

We left the meeting with an understanding to continue our current agreement for our final month of the initial SOW, but to recalculate our cost to deliver the rest of the app - no equity offered.

While we transitioned to this more contractor relationship we couldn't help but have this bad taste in our mouth from the exchange. We had no one to blame but ourselves for our decision to take payment to build our app instead of opting for equity only - but we also poured more than twice the effort into this app than we ever billed with the expectation in our gut that we owned some part of what we were building.

The lesson here is own your work no matter what. Software is worth so much more than what companies pay to build it, so when you have a chance to bet on yourself - do it! If I was re-negotiating our initial deal in hindsight I would demand the price we had initially charged +PLUS a large stake of equity in the finished product.

Graceful Goodbyes

After a few more months of negotiating and planning for phase 2, we were exhausted and disenchanted with the process. In the back of our minds we had our portfolio of apps that we actually owned and craved to maintain. We knew we would never have equity in the project, and any time we poured into the project would only be on a contractor basis. After some serious deliberation the team agreed that Base11 Studios and our apps that we own are our priority - and we walked away from the phase 2 work, handing over our code and accounts along with it. The separation was amicable, but disappointing.

The entire process was a hard-learned lesson, one that I'll always remember as long as I do any freelance work.

Quick Take on 10x Engineers

Mon, 15 Jul 2019 00:00:00 GMT

Just a quick thought on the 10x discussion that is going viral on dev Twitter as I write this post.

My experience in professional software development still relatively brief. That said, I've already seen the '10;1' productivity gap in real life.

However, it hasn't revealed itself as one developer on a team who kicks ass and does the work of five other ordinary devs in terms of rough code output. Instead, the 10x engineers I've seen are the ones who get shit done when it needs to be done. They're the superhero devs, the martyrs, the people who bend over backwards to ship code. They reach out across teams, coordinate with managers, product owners, release management, etc.

Obviously, that's a huge red flag about working environment. There should be no need for a 10x engineer in an organization when everyone is empowered and supported. You shouldn't need one person to be your savior in order to ship code. Any qualified dev off the street should be able to join your team and start shipping code.

To me, the 10x discussion is about startup founders & VC's trying to make their money go a long way by finding that savior dev they can use to build an entire product by themselves. I believe those people exist, and are obviously valuable, but it's not a sustainable way to build an organization or company. And, the 10x engineers aren't going to be the same people to build out that organization.

Finding good engineers is obviously extremely important. How you do it is equally important. Don't sacrifice a 5x engineer hoping for a 10x engineer, and make sure you can keep anyone you hire.

ASWebAuthenticationSession API Changes in iOS 13

Fri, 05 Jul 2019 00:00:00 GMT

One of the biggest announcements at WWDC 2019 was the new 'Sign In With Apple' feature, where Apple will now provide an authentication email & password to apps on behalf of you and manage them securely using the iCloud Keychain.

Apple continues to push these privacy-focused features especially around authentication to try to disrupt ubiquitous services like Facebook & Google OAuth that make login flows much easier for users - but at the cost of their data going into the hands of ad companies.

As such, a lot of focus has been given to the Authentication services in iOS. We saw it begin last year with the move from auth services inside SafariServices to the dedicated AuthenticationServices APIs. This year, iOS 13 leverages AuthenticationServices to enable the Sign In With Apple APIs, and continue to refine the sign in experience.

A Guide to Changes in `ASWebAuthenticationSession`

Last year, I talked a bit about OAuth in iOS in my post about Apple's move from SFAuthenticationSession to ASWebAuthenticationSession and how I went about converting my iOS app to use the new API. This year, the ASWebAuthenticationSession has some smaller tweaks to enhance the OAuth sign-in experience across iOS (including iPadOS) devices.

If you're a developer already sweating about the huge array of changes and opportunities coming for developers in 2019, don't fret about this one, it's a small tweak purely for enhancing OAuth experiences across devices.

To set the stage, let's look at a code snippet for ASWebAuthenticationSession in iOS 12.

//...
var webAuthSession: ASWebAuthenticationSession?
//...
@available(iOS 12.0, *)
func getAuthTokenWithWebLogin() {

    let authURL = URL(string: "https://github.com/login/oauth/authorize?client_id=<client_id>")
    let callbackUrlScheme = "octonotes://auth"

    self.webAuthSession = ASWebAuthenticationSession.init(url: authURL!, callbackURLScheme: callbackUrlScheme, completionHandler: { (callBack:URL?, error:Error?) in

        // handle auth response
        guard error == nil, let successURL = callBack else {
            return
        }

        let oauthToken = NSURLComponents(string: (successURL.absoluteString))?.queryItems?.filter({$0.name == "code"}).first

        // Do what you now that you've got the token, or use the callBack URL
        print(oauthToken ?? "No OAuth Token")
    })
    
    // Kick it off
    self.webAuthSession?.start()
}

In this example, the only thing we need to provide the ASWebAuthenticationSession is the authentication URL, a callback URL scheme, and a completion block that handles the result of the OAuth. The OS handles the rest - displaying an alert, launching a Web login flow, and dismissing.

In iOS 13, as Apple continues to refine the multi-app experience for iOS and iPadOS, we now need to help the OS out when it's making the decision on where and how to display the OAuth Alert and Web login flow.

To do that, we have to let the ASWebAuthenticationSession know which window is presenting the OAuth request. This is done by implementing the ASWebAuthenticationPresentationContextProviding interface in your presenting View Controller.

The presenting View Controller needs to implement the ASWebAuthenticationPresentationContextProviding interface and return the relevant window in the presentationAnchor method.

class LoginViewController: UIViewController, ASWebAuthenticationPresentationContextProviding {
    //...
    func presentationAnchor(for session: ASWebAuthenticationSession) -> ASPresentationAnchor {
        return self.view.window ?? ASPresentationAnchor()
    }
    //...
}

Then, when setting up our auth session, we need to specify our presentationContextProvider delegate.

self.webAuthSession?.presentationContextProvider = context

The full updated method, now passing in a ASWebAuthenticationPresentationContextProviding context (our presenting VC that implements the ASWebAuthenticationPresentationContextProviding interface).

//...
var webAuthSession: ASWebAuthenticationSession?
//...
@available(iOS 13.0, *)
func getAuthTokenWithWebLogin(context: ASWebAuthenticationPresentationContextProviding) {

    let authURL = URL(string: "https://github.com/login/oauth/authorize?client_id=<client_id>")
    let callbackUrlScheme = "octonotes://auth"

    self.webAuthSession = ASWebAuthenticationSession.init(url: authURL!, callbackURLScheme: callbackUrlScheme, completionHandler: { (callBack:URL?, error:Error?) in

        // handle auth response
        guard error == nil, let successURL = callBack else {
            return
        }

        let oauthToken = NSURLComponents(string: (successURL.absoluteString))?.queryItems?.filter({$0.name == "code"}).first

        // Do what you now that you've got the token, or use the callBack URL
        print(oauthToken ?? "No OAuth Token")
    })
    
    // New in iOS 13
    self.webAuthSession?.presentationContextProvider = context
    
    // Kick it off
    self.webAuthSession?.start()
}

At this point, your ASWebAuthenticationSession now knows where and how to display your Web-based login flow, and will provide a consistent experience across devices!

Thoughts on OAuth

It has been an interesting experience tinkering with OAuth over the last two years. Right as I was learning the APIs Apple made a big move to new APIs, and this year it's clear how that change is enabling a better sign in experience for users.

Now, in iOS 13, by observing the specific change in this small API, we can see the evolution of iOS to a multi-window experience.

As I see this slow progression play out, I'm beginning to wonder about the future of OAuth in iOS at all. Will web authentication be blacklisted altogether in favor of Sign In With Apple? Will Apple centralize auth in a way that allows me to authenticate with GitHub without going to GitHub services for tokens? Only time will tell, but the changes today can project the changes in the future - stay alert!

If you have any thoughts/questions/predictions about OAuth and Web Authentication with iOS, don't hesitate to reach out to me on Mastodon.

Web Authentication with iOS AuthenticationServices

Thu, 07 Jun 2018 00:00:00 GMT

Last week I started looking into doing OAuth for an iOS application to enable a simple GitHub authentication flow. After my quick research, I discovered there are more than a couple ways to do this authentication, but the newest and easiest way in Swift was the SFAuthenticationSession that was just introduced in iOS 11.

SFAuthenticationSession offers an easy API to launch a Safari View Controller to a given sign-in url where the user can authenticate through the web. When the OAuth service returns with the auth token, a simple completion handler is called to handle the response. It's simple, secure, and really fast to implement.

Here's my func to authenticate with my GitHub app OctoNotes in Swift:

//...
var authSession: SFAuthenticationSession?
//...
func getAuthToken() {
    //OAuth Provider URL
    let authURL = URL(string: "https://github.com/login/oauth/authorize?client_id=<client_id>")
    let callbackUrlScheme = "octonotes://auth"

    //Initialize auth session
    self.authSession = SFAuthenticationSession.init(url: authURL!, callbackURLScheme: callbackUrlScheme,
                                                    completionHandler: { (callBack:URL?, error:Error?) in

        // handle auth response
        guard error == nil, let successURL = callBack else {
            return
        }

        let oauthToken = NSURLComponents(string: (successURL.absoluteString))?.queryItems?.filter({$0.name == "code"}).first

        // Do what you now that you've got the token, or use the callBack URL
        print(oauthToken ?? "No OAuth Token")
    })

    //Kick it off
    self.authSession?.start()
}

Easy enough! An alert gets displayed to the user prompting them to auth, Safari handles it with their input/with the data it already has, then returns you an authenticated token.

But you'll probably guess if you looked at that link to the SFAuthenticationSession docs that this isn't the end of the story.

`ASWebAuthenticationSession`

On Tuesday at WWDC, in the "Automatic Strong Passwords and Security Code AutoFill" session, Apple announced a new API for authenticating through the web in your iOS apps, and deprecated SFAuthenticationSession. Short life for this handy API.

Not to fear! The replacement for SFAuthenticationSession is ASWebAuthenticationSession, and the new API is very familiar.

Instead of importing SafariServices, start by importing the new AuthenticationServices

import AuthenticationServices

Then follow the same exact pattern to start a ASWebAuthenticationSession and handle the callback to retrive your OAuth Token.

//...
var webAuthSession: ASWebAuthenticationSession?
//...
@available(iOS 12.0, *)
func getAuthTokenWithWebLogin() {

    let authURL = URL(string: "https://github.com/login/oauth/authorize?client_id=<client_id>")
    let callbackUrlScheme = "octonotes://auth"

    self.webAuthSession = ASWebAuthenticationSession.init(url: authURL!, callbackURLScheme: callbackUrlScheme, completionHandler: { (callBack:URL?, error:Error?) in

        // handle auth response
        guard error == nil, let successURL = callBack else {
            return
        }

        let oauthToken = NSURLComponents(string: (successURL.absoluteString))?.queryItems?.filter({$0.name == "code"}).first

        // Do what you now that you've got the token, or use the callBack URL
        print(oauthToken ?? "No OAuth Token")
    })
    
    // Kick it off
    self.webAuthSession?.start()
}

Familiar, eh? The new ASWebAuthenticationSession should enable you to securely authenticate on the web and future-proof your app for any security features involved in web-based login. So while we weep for year-long API's, at least Apple is making the conversion a breeze.