Mobile Development10 min read
Build a Bead Sort Puzzle Game in Flutter
Build a bead sort puzzle game in Flutter with tubes, a pegboard and a tray, a solver that keeps every level winnable, and an ironing payoff for each charm.
- #flutter
- #puzzle-game
- #game-development
- #bead-sort
- #pixel-art

When I built Bead Charms: Pixel Sort Puzzle, I started from a craft table. Fuse beads, a lavender pegboard, an iron and a sheet of ironing paper: tap tubes of beads, fill a pixel art picture on the pegboard, then iron it into a keychain charm. The game now has over 100 original pixel art charms across 8 collections, and every level is checked by a solver so there is always a way through. You can see the finished app in the Bead Charms case study. This guide shows how to build the same game in Flutter: the tube-and-pegboard mechanic, the tray, a solver, difficulty that grows step by step, and the ironing payoff.
What is a bead sort puzzle game in Flutter?
A bead sort puzzle game in Flutter is a puzzle game where the player taps a tube of fuse beads and the top run of matching beads flies onto a pegboard to fill a pixel art picture. Every peg has a target color, and the player sorts the beads by color until the picture is complete. Then the game plays the craft payoff: ironing paper slides over the pegboard, the iron glides across, each bead melts, the paper curls as it peels, and a jump ring and keyring drop on. Bead Charms works exactly this way: 100-plus pixel art charms across 8 collections — Classics, Spooky, Pets, Snacks, Plants, Garden, Winter and Harvest. The mechanic is a cousin of the water sort puzzle, but the pegboard changes the rules: in a water sort game, a tube is either the source or the destination. Here the tubes are only the source, and the pegboard is the only destination, so the player never has to guess where a bead belongs — the picture shows them. That is why the design can stay calm: no timers in the main levels, no pressure, and no purchases.
How does the bead sort mechanic work?
The mechanic works with three pieces of state: the tubes, the pegboard, and the tray. Tapping a tube sends its top run — the longest run of matching beads at the top of the stack — to the pegboard. Beads only land on glowing rows, and the board fills from the bottom row up. A bead with no free peg waits in a small tray and hops on by itself when its row opens. Fill the tray and you are stuck, so every tap needs planning. A tube is a list of bead colors with the bottom bead first, so the top bead is the last item in the list:
enum BeadColor { red, blue, yellow, green, purple }
class Tube {
Tube(this.beads);
final List<BeadColor> beads; // bottom bead first, top bead last
bool get isEmpty => beads.isEmpty;
List<BeadColor> get topRun {
if (beads.isEmpty) return const [];
final color = beads.last;
var count = 0;
for (var i = beads.length - 1; i >= 0 && beads[i] == color; i--) {
count++;
}
return beads.sublist(beads.length - count);
}
void removeTopRun() {
beads.removeRange(beads.length - topRun.length, beads.length);
}
}
Each peg has a target color, so the board can be stored as a count of empty pegs per color. A move is one tap: take the top run from the chosen tube, place each bead on the board when its color has room, and send the rest to the tray. If the tray is full when a bead needs it, the move is illegal and the tube does not move at all:
class BeadGame {
BeadGame({
required this.tubes,
required Map<BeadColor, int> pegsPerColor,
this.traySize = 3,
}) : _emptyPegs = Map.of(pegsPerColor);
final List<Tube> tubes;
final int traySize;
final Map<BeadColor, int> _emptyPegs;
final List<BeadColor> tray = [];
bool _hasRoomFor(BeadColor color) => (_emptyPegs[color] ?? 0) > 0;
bool canTap(Tube tube) {
if (tube.isEmpty) return false;
final overflow = tube.topRun.where((c) => !_hasRoomFor(c)).length;
return tray.length + overflow <= traySize;
}
void tap(Tube tube) {
if (!canTap(tube)) return;
final run = tube.topRun;
tube.removeTopRun();
for (final bead in run) {
if (_hasRoomFor(bead)) {
_emptyPegs[bead] = _emptyPegs[bead]! - 1;
} else {
tray.add(bead);
}
}
tray.removeWhere((bead) {
if (!_hasRoomFor(bead)) return false;
_emptyPegs[bead] = _emptyPegs[bead]! - 1;
return true;
});
}
}
The tray releases beads automatically: a bead that waited in the tray hops onto the board the moment its row opens, so the player never manages the tray by hand.
How do I stop players from getting stuck?
A bead sort level stops players from getting stuck in two ways: the tray absorbs mistakes, and a solver checks every level before it ships so there is always a winning line. The hint system follows the solver's winning line, so a hint never leads the player into a dead end. The solver is a depth-first search over game states: the tubes, the empty pegs per color, and the tray. The search tries every legal tap from a state, and a state is solvable when one of its moves leads to a solved board. A visited set keeps the search from looping forever on the same arrangement. The solver and the game share the same move rules, so a level the solver calls winnable is genuinely winnable by a player:
class BeadState {
const BeadState({
required this.tubes,
required this.needs,
required this.tray,
});
final List<List<BeadColor>> tubes;
final Map<BeadColor, int> needs;
final List<BeadColor> tray;
bool get isSolved =>
tubes.every((t) => t.isEmpty) &&
needs.values.every((n) => n == 0) &&
tray.isEmpty;
String get key =>
'${tubes.map((t) => t.map((c) => c.index).join(',')).join('|')}#'
'${BeadColor.values.map((c) => needs[c] ?? 0).join(',')}#'
'${tray.map((c) => c.index).join(',')}';
BeadState? move(int tubeIndex, int traySize) {
final tube = tubes[tubeIndex];
if (tube.isEmpty) return null;
final color = tube.last;
var count = 0;
for (var i = tube.length - 1; i >= 0 && tube[i] == color; i--) {
count++;
}
final newTubes = tubes.map((t) => List<BeadColor>.of(t)).toList();
final newNeeds = Map<BeadColor, int>.of(needs);
final newTray = List<BeadColor>.of(tray);
final run = newTubes[tubeIndex]
.sublist(newTubes[tubeIndex].length - count);
newTubes[tubeIndex].removeRange(
newTubes[tubeIndex].length - count,
newTubes[tubeIndex].length,
);
for (final bead in run) {
if ((newNeeds[bead] ?? 0) > 0) {
newNeeds[bead] = newNeeds[bead]! - 1;
} else if (newTray.length < traySize) {
newTray.add(bead);
} else {
return null;
}
}
newTray.removeWhere((bead) {
if ((newNeeds[bead] ?? 0) <= 0) return false;
newNeeds[bead] = newNeeds[bead]! - 1;
return true;
});
return BeadState(tubes: newTubes, needs: newNeeds, tray: newTray);
}
}
bool isSolvable(BeadState start, int traySize) {
final visited = <String>{};
bool search(BeadState state) {
if (state.isSolved) return true;
if (!visited.add(state.key)) return false;
for (var i = 0; i < state.tubes.length; i++) {
final next = state.move(i, traySize);
if (next != null && search(next)) return true;
}
return false;
}
return search(start);
}
Run the solver at level-design time, not on the player's phone: generate a level, run isSolvable, and discard or reshuffle any level that fails. Every level the player sees has a way through. The arrow puzzle game guide uses the same idea — a solver-checked board — and it is what makes a calm puzzle feel fair instead of rigged.
How do I scale difficulty across 100 levels?
Difficulty scales with five knobs: picture size, bead shades, tube count, mixed tubes, and tray size. Bead Charms turns them up from level 33 to level 100: bigger pictures, more bead shades, more tubes, more mixed tubes and a smaller tray. After level 100 the puzzle keeps going at the hardest setting. Level 1 teaches the rules with a tutorial hand, and the early levels keep the tray generous.
| Level range | Picture | Shades | Tubes | Tray |
|---|---|---|---|---|
| 1–10 | Small | 3–4 | 3–4 | 5 |
| 11–32 | Medium | 4–5 | 4–5 | 4 |
| 33–60 | Large | 5–6 | 5–6 | 3 |
| 61–100 | Largest | 6–7 | 6–7 | 2 |
| Generate each level from a difficulty profile, then run it through the solver before it ships. The picture decides the bead counts: count the pegs of each color in the finished image, then deal those beads into tubes. The solver is the gatekeeper — if the deal has no winning line, deal again. |
How do I add the ironing payoff?
The ironing payoff is a short animation sequence that plays when the board is complete, and it is the reason the game feels like a craft instead of a sorting chore. It has five beats: ironing paper slides over the pegboard, the iron glides across with steam and sizzle, each bead melts, the paper curls as it peels, then a jump ring and keyring drop on and the finished pixel art swings on the My Charms corkboard. Model the sequence as an enum of phases driven by one animation controller, so the code stays a simple state machine. The payoff matters because it gives the sorting a purpose: without it, the player just clears a board; with it, the player makes something and keeps it. The color-blind friendly game guide covers the same lesson from another angle: a clear reward at the end of a level is what brings players back.
How do I add fair help systems?
Fair help systems are undos, unlimited retries, and hints that follow the solver's winning line. Bead Charms gives the player 3 undos per level, unlimited retries, and a hint hand that points at a tube after 8 idle seconds. Optional rewarded videos give 2 extra tray slots when stuck — once per level — or 3 extra undos. Undos are cheap if the game state is a plain data object: keep a stack of snapshots of the tubes, the board needs and the tray, and pop one back when the player taps undo. The hint timer is a simple idle detector: restart a timer on every tap, and when 8 seconds pass with no move, ask the solver for the next move on its winning line and highlight that tube. The rewarded help stays optional: extra tray slots or extra undos are the player's choice. There are no purchases, and the ads are light — none at launch or in the first two levels, no banners, rewarded videos only when the player chooses.
How do I keep the game relaxing and offline?
A relaxing puzzle game stays offline, portrait-only, and respectful of the player's settings. Bead Charms is fully offline with no account and progress saved on device, plays in portrait on phones and tablets, and offers Sound, Vibration and Reduce motion settings from the first second. The privacy-first offline app guide covers the same on-device storage pattern: local data, no sign-in, and nothing leaving the phone. Reduce motion must actually reduce motion: when the setting is on, beads snap to the board instead of flying in arcs. Haptics and sound are separate switches, and progress saves itself mid-level, so closing the app never loses a half-finished picture.
What mistakes should I avoid when building a bead sort game?
Most bead sort games fail on the same handful of details:
| Mistake | What the player sees | Fix |
|---|---|---|
| No solver check | A level with no solution | Run every level through the solver before shipping |
| A tray that never releases | Beads stuck for no reason | Release tray beads automatically when their row opens |
| Hints that guess | A hint that leads into a dead end | Hints follow the solver's winning line |
| No payoff for finishing | Sorting feels like chores | Iron the picture into a charm for the collection |
| A bead sort game is a small mechanic with a warm payoff: tubes, a pegboard and a tray, a solver, and an ironing sequence that turns a finished picture into something the player keeps. Build it with plain Dart models and check every level with the solver. | ||
| Get in touch and let's talk about your project. |
Frequently asked questions
- How does a bead sort puzzle work in Flutter?
- Tapping a tube sends its top run of matching beads to the pegboard, where beads land on glowing rows and the board fills from the bottom row up. A bead with no free peg waits in a small tray and hops on by itself when its row opens.
- How do I make sure every bead sort level is solvable?
- Run every level through a solver at design time: a depth-first search over tube, board and tray states that tries every legal tap. Discard or reshuffle any level the solver cannot solve.
- How do I scale difficulty in a bead sort game?
- Turn up five knobs step by step: bigger pictures, more bead shades, more tubes, more mixed tubes and a smaller tray. Bead Charms turns them up from level 33 to level 100, then keeps going at the hardest setting.
- How do I add hints that never mislead the player?
- Follow the solver's winning line: restart an idle timer on every tap, and after 8 seconds with no move, highlight the next tube on the solver's line. The hint points, and the player still taps.


