BirdBrainz

Fowl Play for Puzzle Lovers: Challenge your brain with unique bird-placement puzzles: quick to near impossible. 5 puzzle sizes, 6 selectable difficulty levels, Thousands of puzzles, 9 birds

Comment 1

Inspiration

BirdBrainz is the classic Queens puzzle but with more personality and a more approachable learning curve.

I've always been intrigued with logic puzzles: LodeRunner, Sokoban, Sudoku, Only Connect, etc. A few months ago, I got caught up in the Queens puzzle wave. It's a nice, visual form of the kind of deduction loop you get from a Sudoku or a good crossword.

I had my issues with the games that are out there, though. Queens puzzles tend to be rigid, mathematical and intimidating to new users. In particular:

  • These games have a steep learning curve.
  • Most Queens-like games can give pretty cryptic clues when you're stuck. "Placing a piece there will cause a contradiction." - What contradiction? Explain it to me so I can learn.
  • A good puzzle lets you use your whole brain. The Queens puzzle genre tends to have identical pieces, making it harder to reason about verbally as well as spatially. "If I put one penguin here then I can't put another penguin there or there" is frustrating when trying to use your linguistic reasoning. Much better to have individual pieces that can be talked about: "If I put the cardinal in row 9, then the blue jay can't be in row 8 because of the goldfinch."
  • Players often don't have control over what puzzle they play next. Either the game enforces a rigid sequence, or it offers only one puzzle per day.
  • These games tend to be visually flat. Even the ones that add animal mascots in place of chess pieces end up with all the pieces appearing the same.
  • I wanted to play on my phone, but most games start at 10 rows and columns, making the board tiles too small to work with well on a small device.
  • One thing that mobile games can do especially well is color and personality. I wanted lots of personality and more color.

What it does

BirdBrainz is the Queens puzzle reimagined in a world of birds that only get along when they're in the right position (think bickering 5th graders that need to be arranged in the right seating positions). Each puzzle has only one answer. As with most games in this genre, the rules are simple:

  • only one bird per colored region (BirdBrainz calls it the bird's "home")
  • only one bird per row
  • only one bird per column
  • birds can't be adjacent to one another, even diagonally

But instead of one identical piece that gets placed on the board 9 times, there are 9 different colored birds, each with its own colored "home" region.

  • Try to place a bird in the wrong home and he flies back to his perch.

  • If the player places a bird illegally, one bird will chase off the others and they'll return to their perch, ready to be placed again.

Those two fundamental gameplay changes make the game much more approachable and fun. Birds can chase each other in angry animated loops until the right answer is hit upon, then they seem to snap into place and the screen switches from a grid to a happy tree canopy.

Players get to choose the difficulty of their next puzzle and are given a board between 5x5 and 9x9. Progressive sizes and difficulties reveal themselves as the player succeeds at earlier puzzles.

If the player's stuck, they have the choice to Start Over and move all birds back to their perch, Give Up and choose an easier puzzle, or ask for a Hint.

Hints tell the user the next logical step they could take, and hints don't correct misplacements. So they act as a nudge, not as a way to speed run to a solution.

Between puzzles, users are shown either a bird fact or, occasionally, a fake ad. Ads are meant to break the rhythm of the puzzle-solving loop. They're fake ads for a fictional "bird world" where birds are marketed to in the same way that we are in our world.

There's a single lifetime unlock IAP that lets the user turn off the fake ads and also have unlimited hints. Users are offered the paywall when they're presented with an ad or when they've exhausted their available hints.

How I built it

The project was built in Xcode using SwiftUI. TDD was hugely important in the building of the puzzle generator (see below). Claude and CODEX were both used in a spec-driven development approach, giving Claude short coding sprints under direction and asking CODEX to document, test and look for bugs or open loops. ChatGPT was used for planning, research, feature exploration and UI mockups.

Background music and sound effects were built in GarageBand.

The birds themselves are SwiftUI compositions: shapes, gradients, foreground styles and triggered animations. Clouds, game tiles, tree branches and all other environmental graphics are also built programmatically. Unlike most games with this much graphical richness, there are only 4 assets in the main Asset catalog for the game.

The fake ads are static image assets that were generated with ChatGPT. They make up the majority of the graphical assets in the bundle, far outnumbering the gameplay assets.

Challenges I ran into

Puzzle Generation

Puzzles had to be tunable by difficulty, variable in puzzle size, have unique solutions and offer all users essentially the same experience (given their own choices).

This design requires a lot from the generator. Puzzles are broken up into 5 sizes from 5x5 to 9x9 and into 6 difficulty levels. Players get to choose the difficulty of their next puzzle. They're allowed to choose up to 1 difficulty level above the highest level they've solved. Within each difficulty level, larger sizes become available as more puzzles are solved. The game then pseudo-randomly picks a puzzle out of the available sizes.

To support this, puzzles are generated using a random number generator with a sequential seed. Difficulty is determined by an algorithmic solver that establishes what kinds of deductions are needed to solve a puzzle and how many steps it will take (see below). The next puzzle is selected for the player based on the difficulty they chose and the sizes that are available to them. So there are thousands of puzzles available to the player at every difficulty level and size (for example, in testing, my generation tool produced more than 1,000,000 7x7 puzzles without encountering a duplicate).

A puzzle solver sequentially solves the puzzle even as it's being generated, ensuring that a unique puzzle is generated in a time-efficient manner. At each step of the solve, it determines every next deduction that can be performed on the puzzle (place birds that have only one cell left, mark off illegal cells, identify naked doubles, etc) and does each one before iterating on the new state of the puzzle. This ensures that the choice of which deduction to do first doesn't cause a discrepancy in difficulty. Deductions are weighted in difficulty to come up with an overall difficulty score (sort of like a quarterback rating in football; there's no normalization, just a raw score). Difficulty bands were determined by looking at the corpus of difficulty scores for the first 10,000 puzzles of a given size and breaking them up into reasonable bands. The difficulty distribution forms something pretty close to a classic Gaussian curve with "beginner" and "champion" occupying the extremes.

The end result is that the player feels in control of the challenge they are giving themselves while seeing a brand new puzzle every time and getting one that they're likely to be able to solve with enough effort.

The hint system grew naturally out of the puzzle generator/solver. Since the solver knows the available next deductions for solving the puzzle, it can be reused to provide hints (with just a few extra states that a human is likely to do but an algorithm won't).

Monetization

I wanted this game to feel approachable and friendly. I didn't want the user to feel that they're being marketed to. I wanted very tight control of the user experience throughout. Yet the natural fit for an app like this is rewarded ads with an optional IAP to turn them off.

Conventional ad networks weren't a great fit for BirdBrainz in particular. I wanted tight control over the interaction loop, didn't want advertising to introduce additional tracking or permissions, and wanted even the interruptions between puzzles to feel like part of the BirdBrainz world.

So I invented "Rectrix Fifth Avenue" - a fictional ad agency that serves mobile ads to birds. When the app shows an ad, it doesn't show an ad from one of the industry ad platforms. Instead, it shows a (clearly AI-generated) image asset of an ad targeted toward birds. The birds in this fictional world have their own fashion lines, technology companies, social networks, movies and more. Ads are shown after a ~10 second loading period and are closable after ~15 seconds (both variable to simulate real ad networks). The point is to give the cadence of an ad-supported game without third-party tracking, SDKs or surrendering control over what appears in the app. It's a silly, surreal joke that solves a user trust problem.

I had already written the code for a true AdMob integration when I came up with the idea for Rectrix Fifth Avenue, so it was a simple matter of swapping in a custom "ad framework" for AdMob.

Organic Visual Design

I was emphatic early on that I didn't want to use image assets for the birds in the game. I wanted them to animate on command in interesting ways that I could tune over time. Creating animated GIFs is not my specialty. SwiftUI offers a strong set of primitives for this kind of thing, but it took a lot of tuning and design thought to get animations and interactions right. Birds are a composition of individual bird body parts, each with its own drawing process. The birds are animated through my own animation controllers which dispatch animation events to each bird to animate individual parts and thus derive the character-driven animations that appear on-screen. Getting the conflict animations that run when one bird chases off another has been a constant design and technical challenge with regular iteration over the last couple months.

The branches that the birds land on were another design challenge. In each puzzle, the birds end up in a different position, so the branches have to accommodate a whole variety of positions while following certain obvious rules (they can't cross, they have to grow in from both sides of the screen, etc). So I couldn't use assets for this either. I had to design a set of primitive, composable tree parts (branches, petioles, leaves) and then compose them into tree limbs. I ended up with a system where a tree limb is represented by a series of connected nodes that alternate between straight stretches for the birds to sit on and splines between those sections. A turtle draws around the skeleton to form the closed path that SwiftUI fills in. This ended up using a programming skill I hadn't used since my Tandy 1000 when I used to play with LOGO.

Onboarding

Writing a tutorial that is accessible both to people who know the genre and who have never seen it before was a challenge. It took many iterations to get right. Interestingly, helping people understand the value of marking a tile as off-limits for a bird was one of the hardest UI challenges of the whole project. When I finally added a shimmer effect to the tiles that needed to be marked, things seemed to click.

Sound Design

It became apparent early on that this game needed sound that matched its own character. I had played around with GarageBand before, but never used it to make something for other people.

I wrote three individual compositions (12-bar, 12-bar and 4-bar), all at the same tempo and in related major keys. I wrote a controller that switches between them at measure breaks when the user switches from one game context to another.

Sound effects were a matter of finding GarageBand instruments that sounded sufficiently "bird-like" to my ear and coming up with short phrases that match the tempo and key of the theme music. It was a fun evening of exploration.

UI Design

I started out with a pretty custom design language. Over the course of time, I ended up using the native iOS controls and layout more and more. Once Xcode 27.1 beta came out and I could test the game against the iPhone Duo simulator, I switched to using mostly system-native controls and only using custom controls for the main gameplay and difficulty selection surfaces.

Accomplishments that I'm proud of

I've been writing software independently for a while, and I've even had some moderate success in the past, but I've never taken on a graphically rich puzzle game before. I always felt my coding proficiency was more prosaic than what's needed to produce something as elaborate as BirdBrainz. I also never wanted to take on the various other roles (art design, sound design, ad integration). I'm a programmer (and designer), not a marketer.

But apparently I can also do basic sound design, (fake) ad copy, silly bird puns, level design, difficulty progression, etc.

BirdBrainz meets the design goals that I had laid out. It's a more approachable, more whimsical, more forgiving take on a popular game genre. It has a unique, gradual and challenging progression system. It has a monetization strategy that doesn't give up user privacy or give up control of the app to third parties. It has an organic, opinionated visual design. And all these things fit together and complement one another.

What I learned

I had a couple family members that helped me test every few days. They were very helpful because their approach to these kinds of puzzles is more "guess and check" than "deduce the answer" like my approach. When I could make the game both approachable and challenging for myself and for them, that's when I knew I had something worthwhile.

I had one testing session with a family with three daughters aged 3, 11 and 11. Parents and children both wanted to play. The three-year-old even wanted a turn dragging the birds around the screen (and she helped me find a bug when she tried to drag a bird that shouldn't have been draggable). The preteens skipped parts of the tutorial, had totally different opinions of how to play, challenged each other to try harder difficulties, and coached one another's next moves. The parents were anxious to tell their daughters how to solve a given puzzle, having to hold themselves back. They asked questions at about the points I expected them to, then found the answers in the game without needing me to explain. They played for over an hour and didn't want to stop. Importantly, the preteens got to go through the tutorial and the parents didn't, yet everyone grasped the game within about 5 minutes. "Oh, it's like Sudoku with birds."

And importantly to me, everyone seemed to like the theme music.

I also learned that I have the skillset needed to take on larger projects as an independent developer. I learned a great deal about birds while researching bird facts to go between the puzzles. I learned about the history of advertising while putting together the Rectrix Fifth Avenue ads. I learned that a German word for "flock of birds" is "Vogelschwarm" (the inspiration for one of the ads). I learned that when the iPhone Duo comes out, I'm going to have an app that's most of the way to being ready for it on day one.

What's next for BirdBrainz

Leaderboards for each puzzle are first on the list. Who solved it best (fewest mistakes, fewest hints) and who solved it first.

I'm also considering daily puzzles so that users can compare themselves against one another in a fair and continually varied way. This would be a second layer of gameplay, not a replacement for what's already there. Each day there would be a new puzzle. They would progress in difficulty over the week. Leaderboards would tell you who solved it first and best.

And I have several folders of new ads to be added to the app over time.

Built With

  • garageband
  • spec-driven-development
  • spm
  • swift
  • swiftui
  • tdd
  • xcode
Share this project:

Updates

Submission history