The rules

TANDEM is a 6×5 grid with 7 to 9 wall tiles and two pieces, 1 and 2. Each piece has its own station. There is only one set of arrows: when you press left, both pieces try to move left at the same time. A piece that would hit a wall or the edge stays where it is. If both pieces would end up on the same cell, or would swap cells, neither moves. This is the real step function from shared/logic.ts:

export function tandemStep(c: TandemConfig, positions: [number, number], dir: Direction): [number, number] {
  const step = (p: number) => {
    const x = p % c.width, y = Math.floor(p / c.width);
    const [dx, dy] = dir === 'up' ? [0, -1] : dir === 'right' ? [1, 0] : dir === 'down' ? [0, 1] : [-1, 0];
    if (x + dx < 0 || x + dx >= c.width || y + dy < 0 || y + dy >= c.height) return p;
    const next = p + dx + dy * c.width;
    return c.walls.includes(next) ? p : next;
  };
  const a = step(positions[0]), b = step(positions[1]);
  // A shared destination or a swap leaves both couriers in place.
  return a === b || a === positions[1] && b === positions[0] ? [...positions] : [a, b];
}

One detail: a piece may step into the cell the other piece is leaving, so they can move in a line. They only both stop when the other piece is stuck in that cell (a === b) or when they would swap. The whole game is about using walls to stop one piece while the other keeps going.

The state is the pair

You can't plan each piece on its own, because every arrow moves both. A position in the game is the pair (cell of piece 1, cell of piece 2). Cells are numbered 0 to 29, so the search keys a pair as p1 * 30 + p2. With 7 to 9 walls there are 21 to 23 floor cells, and the pieces never share a cell, so there are at most 23 × 22 = 506 positions, each with four arrows out of it. That is small enough to search completely, on the server when the puzzle is made and in the browser while you play.

The search, from the same file:

export function tandemSearch(c: TandemConfig, from = c.start, goal: [number, number] | null = c.goals) {
  const size = c.width * c.height, key = (p: [number, number]) => p[0] * size + p[1];
  const queue = [{ positions: [...from], parent: -1, dir: null }];
  const seen = new Set([key(from)]), output = [];
  for (let head = 0; head < queue.length; head++) {
    const node = queue[head];
    if (!goal || node.positions[0] === goal[0] && node.positions[1] === goal[1]) {
      const path = []; let at = head;
      while (queue[at].parent !== -1) { path.push(queue[at].dir); at = queue[at].parent; }
      output.push({ positions: node.positions, path: path.reverse() });
      if (goal) return output;
    }
    for (const dir of DIRECTIONS) {
      const next = tandemStep(c, node.positions, dir), id = key(next);
      if (!seen.has(id)) { seen.add(id); queue.push({ positions: next, parent: head, dir }); }
    }
  }
  return output;
}

(I trimmed the type annotations on the locals; the logic is unchanged.) The queue is a plain array with a moving head index, and it doubles as the parent table, so a path is rebuilt by walking parent links back to the start. Give it a goal and it returns the shortest route to that goal. Pass null and it returns every reachable position, each with a shortest route to it. That second mode is the generator.

Generate backwards: pick the goal last

The obvious way is to put the stations somewhere at random and then check that the puzzle can be solved. I do it the other way round: place the walls and the two pieces, run the search from the start with no goal, and then pick the stations from the positions the search found at the distance I want.

export function generateTandem(seed: string): PrivatePuzzle {
  const rng = randomSource(`tandem-v1:${seed}`), all = Array.from({ length: 30 }, (_, i) => i);
  for (let attempt = 0; attempt < 100; attempt++) {
    const walls = shuffle(all, rng).slice(0, 7 + Math.floor(rng() * 3)), floor = all.filter(i => !walls.includes(i));
    if (!connected(floor, 6, 5)) continue;
    const start = shuffle(floor, rng).slice(0, 2) as [number, number];
    const config: TandemConfig = { kind: 'tandem', width: 6, height: 5, walls, start, goals: [...start] };
    const candidates = tandemSearch(config, start, null).filter(s => s.path.length >= 9 && s.path.length <= 15 && s.positions[0] !== start[0] && s.positions[1] !== start[1]);
    if (!candidates.length) continue;
    const chosen = candidates[Math.floor(rng() * candidates.length)];
    config.goals = chosen.positions;
    return { config, solution: { path: chosen.path, par: chosen.path.length } };
  }
  // The fallback uses the same validated generator, with a fixed independent seed.
  if (seed !== 'tandem-fallback-v1') return generateTandem('tandem-fallback-v1');
  throw new Error('No bounded tandem layout');
}

That gives me a few things without extra code:

• The puzzle can always be solved, because the stations are a position the search actually reached.
• The par is exact. BFS finds positions in order of distance, so the route stored with each position is a shortest one. Par is somewhere from 9 to 15 moves.
• Neither piece starts on its own station (the !== start checks).
• The stored route is what the game shows as the replay after you finish.

connected is a plain flood fill over single floor cells. It is only a cheap first filter: a connected floor doesn't mean every pair of cells can be reached, because the pieces move together. The pair search makes the real decision.

A real board

This is the board from the cover image, a screenshot I took while testing (# wall, 1 and 2 the pieces, a and b their stations):

. . . # # #
. . . . . .
# . . # b #
. . . . . .
. a . # 1 2

From the start, only "up" does anything. Left: piece 1 hits the wall and piece 2 would move into its cell, so both stay. Right: piece 1 would move onto piece 2, which is stuck at the edge, so both stay. Down is the edge. The search reaches 448 of the 506 possible positions, 155 of them are 9 to 15 moves away, and the stations it picked are 9 moves away: up, left, up, up, left, down, right, down, left.

What I measured

I wanted numbers rather than impressions, so I ran a copy of the generator loop with counters on 1,000 made-up seed strings, and checked that every puzzle it made was identical to what generateTandem returns for the same seed:

• 485 seeds got a puzzle on the first attempt. The worst one needed 15 attempts out of the 100 allowed, and the fallback seed was never used.
• All 1,062 rejected attempts were wall layouts that split the floor into separate areas. Not once was the list of candidate goals empty.
• Reachable positions per puzzle: median 446, minimum 197, maximum 506.
• Par: 251 puzzles at 9 moves, 207 at 10, 162 at 11, 147 at 12, 104 at 13, 74 at 14, 55 at 15.

That last line is skewed toward short routes, and the reason is in the code: I pick uniformly among positions, not among lengths, and there are fewer positions far from the start. In the example board the search found 83 positions at distance 9, 47 at 10, 24 at 11, 10 at 12 and none further. If I wanted each length equally often, I would pick a length first and then a position at that length. So far I've left it as it is.

Two more things the counters showed. The median puzzle has 3 different shortest routes, and 254 of the 1,000 have exactly one, which is why the replay says "one of the shortest routes". And a move can't always be reversed with the opposite arrow: if one piece was stuck and the other moved, the opposite arrow can move both. So in principle you can reach a position from which the stations can't be reached at all. Only one of the 1,000 puzzles had any such position. The game still handles it: the max score shows a dash and a line says "No route from this position. Undo or restart to continue."

Hints and scoring use the same search

A hint is the first step of tandemSearch(c, state.positions), the shortest route from where you are now. The score is:

export function tandemPoints(actions: number, par: number) {
  return Math.max(10, 100 - Math.max(0, actions - par));
}

Every move, undo, restart and hint counts as an action. A press that moves neither piece is refused and costs nothing. Solving always gives at least 10 points. The browser runs the same search after each move to show the best score you can still get: actions so far plus the remaining shortest route, passed through the same function. So the number on screen and the number the server saves come from the same code.

The seed itself comes from a signed day key, and the finished puzzle is stored once per day, so everyone gets the same board. I described that part in the previous post.

What I'd still like to know

Par length is only a rough measure of difficulty. A long route can be mostly plain walking, and a short one can hinge on a single moment where one piece has to be held against a wall. I could try other measures, like the number of shortest routes or how many steps of the route depend on one piece being stopped, but I haven't decided which one matches how hard a day feels. If you make generated puzzles, how do you rate difficulty?

Today's board is at nocturne-island.com.

The puzzle

BLOOM has six pumps and six flower beds. Each pump has a setting from 0 to 3 and feeds two or three beds. A bed gets the sum of the settings of every pump connected to it. The board shows which pump feeds which bed and how much water each bed needs. You find the six settings.

The whole "physics" of the game is one function:

// links[p] = the beds pump p feeds, levels[p] = its setting (0–3)
function bloomWater(c: BloomConfig, levels: number[]) {
  return c.targets.map((_, bed) =>
    c.links.reduce((sum, beds, p) => sum + (beds.includes(bed) ? levels[p] : 0), 0));
}

If you squint, that's a 6×6 system of linear equations, A · x = t. A[bed][pump] is 1 when the pump feeds the bed, x holds the pump settings and t the targets. That's exactly why uniqueness doesn't come for free. Random wiring regularly gives you two pumps that feed the same beds, or a pump whose beds are covered by a combination of other pumps. Then you can move water from one pump to another and still hit every target.

The game scores by comparing water, not settings, so a second answer wouldn't be marked wrong. But the puzzle would stop being a deduction puzzle. At some point you'd have to guess. And the hint button ("set the first wrong pump to its correct value") would point at one specific answer, possibly overwriting a perfectly valid one you were heading towards.

Build the answer first, then reject

The generator isn't clever. Each attempt goes like this:

1. Wire each pump to 2 or 3 random beds.
2. Build the matrix and throw it away unless it has full rank.
3. Pick the hidden settings and compute the targets from them, so a solution exists by construction.
4. Reject boards whose targets fall outside 1–7 or that have too few pumps actually running.

Simplified, but faithful to the real code:

function generateBloom(seed: string) {
  const rng = randomSource(`bloom-v1:${seed}`), beds = [0, 1, 2, 3, 4, 5];
  for (let attempt = 0; attempt < 100; attempt++) {
    const links = beds.map(() => shuffle(beds, rng).slice(0, rng() < .5 ? 2 : 3));
    const matrix = beds.map(bed => links.map(fed => Number(fed.includes(bed))));
    if (!fullRank(matrix)) continue;           // could have more than one answer
    const levels = pickLevels(rng);            // the hidden answer
    const config = { kind: 'bloom', links, targets: beds.map(() => 0) };
    config.targets = bloomWater(config, levels);   // clues come from the answer
    if (config.targets.some(n => n < 1 || n > 7)) continue;
    return { config, solution: { levels } };
  }
  return generateBloom('bloom-fallback-v1');   // fixed seed known to pass
}

Why full rank is enough: if A is invertible, A · x = t has exactly one real solution, so there's at most one with whole numbers from 0 to 3. And we know one exists, because we built t from it.

Two details I got wrong in my head before getting them right in code:

Use the right field. It's tempting to think "0/1 matrix, do it mod 2". That would be wrong, because water adds like normal numbers. A matrix can be singular mod 2 and still invertible over the reals: three pumps wired in a triangle ([1,1,0] [0,1,1] [1,0,1]) has determinant 2. So fullRank is plain Gauss–Jordan elimination over floats with a small tolerance. With a 6×6 of zeros and ones, that's perfectly safe.

Full rank is sufficient, not necessary. A singular matrix can still have only one solution inside the 0–3 box, because the "other" answer would need a negative setting or a 4. I reject those boards anyway. It costs a few extra attempts and keeps the guarantee simple enough that I can actually trust it.

Let brute force be the referee

The rank check is fast and runs every time a puzzle is generated. But it's a clever argument, and clever arguments break quietly when you change the rules later (say, four beds per pump). Luckily the space is tiny: 4⁶ = 4096 settings. So the tests just try all of them:

export function solveBloom(c: BloomConfig): number[][] {
  const solutions: number[][] = [];
  for (let mask = 0; mask < 4 ** c.links.length; mask++) {
    let v = mask;
    const levels = c.links.map(() => { const n = v % 4; v = Math.floor(v / 4); return n; });
    if (bloomWater(c, levels).every((w, i) => w === c.targets[i])) solutions.push(levels);
  }
  return solutions;
}

// for 100 independent daily seeds:
assert.deepEqual(solveBloom(c), [puzzle.solution.levels]);

Exactly one solution, and it's the stored one. The same test then plays those settings through the server's own rules function and expects a score of 100. The rank check is the guarantee at generation time, and the brute force is how I know the guarantee is real.

Same puzzle for everyone

Generation is deterministic. The PRNG is tiny: an FNV-1a hash of the seed string feeds a mulberry32-style generator, and every game gets its own namespace (bloom-v1: plus the day seed). The day seed is an HMAC of the UTC date and game name with a server-side key, so tomorrow's board can't be computed in advance.

The first request of a day generates the puzzle and stores it in SQLite keyed by (day, game) with INSERT OR IGNORE, then reads back whatever row is stored. Two simultaneous "first" requests still serve the same puzzle. A later code change can't rewrite a day that has already been played either, because stored days are never regenerated. The browser only receives the wiring and the targets. The hidden settings stay on the server until you finish.

Scoring that forgives being close

Exact answers are the goal, but near misses shouldn't score zero. Each bed scores 1 − |water − target| / target, floored at 0. The six beds are averaged and multiplied by 100. Too much and too little water cost the same, and twice the target is as bad as leaving a bed dry. A hint sets the first wrong pump to its correct value, locks it and costs 15 points.

What I'd take to the next generator

• Construct the answer first and derive the clues from it. Existence is then free, so you only have to fight for uniqueness.
• Find a cheap, conservative uniqueness check for the generator, even if it rejects some good boards.
• When the search space is small, brute-force it in tests. It's the cheapest proof you'll ever write.

If you try today's BLOOM at nocturne-island.com, I'd really like to hear how it went. Did the wiring feel solvable by reasoning, or did you end up nudging pumps until the numbers matched? And if you've built puzzle generators yourself, do you check uniqueness at generation time, only in tests, or both?