DEV Community: Focss

Reading 839 Game Boards Out of Screenshots with OpenCV and k-means

Focss — Tue, 20 Oct 2026 12:11:13 +0000

Reading 839 game boards out of screenshots with OpenCV and k-means

I run Block Out Guide, a fan site for the mobile puzzle game Block Out! - Color Sort Puzzle. Every published level gets a static page with its video walkthrough, a board screenshot, and links to the neighbouring levels.

The easy version of that site is a template: fill in the level number, embed the YouTube video, done. But then every page says essentially the same thing. A player stuck on level 412 already knows the level number. What they don't know is what the board looks like.

The site already had one screenshot per level: the YouTube thumbnail, 1280×720. So I wrote extract-board-data.py, a Python script that reads the board out of each screenshot and emits a JSON description: palette, colour shares, background, and a compact layout map. It currently covers 839 boards, and the whole output is about 1.1 MB.

This post covers the image-processing decisions, including the ones that did not work the first time.

The screenshots are not standardized

There are two templates in the playlist:

a promo card, with the board on the left and the "BLOCK OUT" logo on the right;
an in-game screenshot, with the board in the middle, the logo on the left and a player watermark on the right.

So a fixed crop is out. It would either clip landscape boards or include the logo. Both templates do put the board inside the same purple rounded frame, so the first idea was to find the frame.

The frame works for most promo cards. On some boards, though, blocks in blue or purple pass the same colour test as the frame, and landscape boards are wider than they are tall, which breaks the frame's assumed proportions.

Find the board with a content mask

The second approach looks for the most vivid blob in the middle band of the image. The character sits to the left of the board; the promo logo and the watermark sit to its right. So the scan is restricted to x = 205..860, keeping pixels with high saturation and value, then closing the gaps and taking the largest connected component.

hsv = cv2.cvtColor(a, cv2.COLOR_RGB2HSV)
mask = ((hsv[..., 1] > 110) & (hsv[..., 2] > 100)).astype(np.uint8) * 255
mask[:, :BOARD_SCAN_X0] = 0
mask[:, min(w, BOARD_SCAN_X1):] = 0
kernel = cv2.getStructuringElement(cv2.MORPH_RECT, (17, 17))
closed = cv2.morphologyEx(mask, cv2.MORPH_CLOSE, kernel)
n, _, stats, _ = cv2.connectedComponentsWithStats(closed)

The morphological close is what makes this work. Individual blocks are separated by thin dark gaps, and a 17×17 closing kernel bridges them into one component, so the board becomes one blob instead of a pile of separate rectangles.

Components smaller than 140×140 are discarded, and the largest remaining one by area wins. The fixed side margins keep the character and the watermark out of the result.

Ignore the frame, keep the pale blocks

The content box is still slightly too large: it includes part of the rounded purple shell. My first instinct was to trim it by saturation, which deletes white and pale blocks sitting on the edge. Boards with white pieces at the border made that obvious.

The fix is to measure the frame's own colour instead of assuming it. The script samples the purple frame mask inside the detected box, takes the median, and keeps the page navy as a constant. A pixel counts as content only if it is far enough from both:

frame_distance = np.abs(region - frame_rgb).sum(axis=2)
page_distance = np.abs(region - PAGE_RGB).sum(axis=2)
content = (frame_distance > 55) & (page_distance > 28)

The thresholds are sums across the three RGB channels, so 55 means roughly 18 per channel. That is cheap, and it held up across both templates. The tight bounding box of the content is then inset by 3% to drop anti-aliased edge pixels, with a floor of 3 pixels so it does not eat a real edge column.

Sample a lattice. Do not pretend it is the game grid

Next question: what is the cell grid? The honest answer is that it varies by level, and I do not have the game's internal map data. So the script does not try to recover the exact grid. It samples a fixed 20×28 lattice and takes the median colour of each patch.

for j in range(GRID_NY):
    for i in range(GRID_NX):
        patch = sub[py0:py1, px0:px1]
        cells[j, i] = np.median(patch.reshape(-1, 3), axis=0)

Median rather than mean: the blocks are flat shaded, but there are highlights, shadows and anti-aliased boundaries. The median throws those away. A mean would smear a boundary pixel into the cell colour.

The published data is colour shares and layout samples. A 20×28 sampling grid gives a stable resolution for comparing boards and a readable map. It does not claim the game has exactly 560 cells.

Cluster the colours in Lab, merge by hue

Each board has 3 to 13 distinct colours, with a median of 8. But k-means on raw RGB with k=14 splits one colour into its highlight and shadow variants. So the pipeline converts the samples to CIE Lab, runs k-means, and then merges the fragments.

The merge rules are deliberately asymmetric:

chromatic clusters merge when the hue distance is at most 14° and the saturation difference is at most 0.25;
achromatic clusters (chroma ≤ 25) merge by value, with a tolerance of 28/255;
when a tiny cluster is folded into a neighbour, Lab distance down-weights lightness by a factor of 0.35.

def swarm_distance(lab_a, lab_b):
    return float(np.sqrt((lab_a[1] - lab_b[1]) ** 2 + (lab_a[2] - lab_b[2]) ** 2)
                 + LIGHTNESS_WEIGHT * abs(lab_a[0] - lab_b[0]))

One special case: the navy empty board and the purple frame share a hue. Merge purely by hue and they collapse into one cluster, after which the background gets reported as the frame. The fix is a lightness split. If both clusters sit in hue 220 to 285 and one is dark (value below 0.48) while the other is bright (value above 0.55), the script keeps them separate.

Clusters below 2% of the sampled cells are folded into their nearest neighbour, so a stray highlight does not become a palette entry.

Name the colours and find the empty board

Palette entries get coarse names from hue (red, orange, yellow, green, cyan, blue, purple, pink) plus greys by value. Duplicate names are disambiguated with lightness bands, which is where names like "pale blue" and "light blue" come from. Two greens that land in different bands are different colours on screen.

Then there is the background. The empty board is the largest dark-blue group that is not the frame. The criteria: blue leads red and green by at least 15, value is below 0.68, saturation is below 0.80, and the group covers at least 8% of the board. A bright blue block fails that test.

Every sampled cell is then assigned to its nearest remaining group in Lab. Cells excluded as frame or page become . in the map. Percentages are re-based on the assigned cells, so the published map and the published numbers cannot disagree. Finally the palette is sorted so index 0 is always the largest colour.

The output

Each level ends up with a compact record like this (real data from level 1):

{
  "b": [251, 62, 703, 669],
  "g": [20, 28],
  "bghex": "#232460",
  "bgname": "navy",
  "bgpct": 27.0,
  "c": [
    {"hex": "#EDE7E7", "name": "white", "pct": 17.3, "cells": 80, "edge": 5, "center": 12},
    {"hex": "#343234", "name": "near-black", "pct": 14.0, "cells": 65, "edge": 8, "center": 46},
    {"hex": "#EBA512", "name": "orange", "pct": 13.4, "cells": 62, "edge": 21, "center": 79}
  ],
  "l": [
    "....................",
    "223333333222444444..",
    "223333333222444444..",
    "223333332222444444.."
  ]
}

The edge and center fields are the share of a colour's cells in the outer two-cell border versus the central half of the board. They exist so a page can say "this colour mostly sits at the edges" without shipping the full map to every visitor.

The layout uses base-36 characters, so up to 36 colours can be encoded without changing the format. In practice the maximum is 13.

Running it over 839 images

A few operational details that saved time:

The script reads from a local R2 WebP dump first and only fetches a missing thumbnail over HTTP, with exponential backoff, into a gitignored cache.
ProcessPoolExecutor runs across all CPU cores with chunksize=8. The work is pure numpy and OpenCV, so processes are the right tool; per-image work does not benefit from threads in Python.
--limit is the smoke test. --min-id / --max-id re-run a range and merge the results into the existing JSON, so fixing ten bad boards does not mean redoing 839.
The final JSON is written with compact separators and keys sorted numerically. That keeps the payload small and the diffs stable.

Current stats: 839 boards, 3 to 13 colours per board (median 8), and 578 boards with a detected empty-board background. The other 261 boards did not meet the background test.

What this data is not

The limits:

The map is not the game's exact grid. It is a 20×28 sampling lattice, so the shares describe the artwork, not legal moves.
It says nothing about doors, paths or solvability. That would need the game's own data.
The input can lie. Levels 1 to 10 share a single compilation video, so they share one thumbnail and produce ten identical board records.
Template changes break it. The side margins that exclude the character and watermark are constants. A new screenshot layout would need those adjusted.

Even with those limits, each level page gets a palette, the dominant colours, and a map of where they sit. A player deciding whether to attempt a board can use that.

The script is about 650 lines including comments, and the pipeline is deliberately boring: NumPy, OpenCV and Pillow, no ML model, no GPU. If you are doing something similar with game screenshots, the two decisions that mattered most were measuring the frame colour instead of thresholding saturation, and being honest that the sampling grid is a sampling grid.

The site it feeds: https://block-out.org/

Two bugs I hit building a 575-page Next.js site with no server

Focss — Sat, 17 Oct 2026 04:47:31 +0000

I run a guide site for Sand Blocks: Drop Puzzle, a mobile physics puzzle where you pull colored sand into pits. Every level gets a page with a video, a board image, and a short written guide. Right now that is 575 level pages, plus a searchable index, range hubs, a blog, and the usual about, contact, and privacy pages. The sitemap has 607 URLs.

The site has no accounts and no user-generated content. New levels arrive in batches every week or two. A rebuild is a perfectly good content update mechanism, so I set output: "export" and kept the database out of the request path.

const nextConfig = {
  output: "export",
  images: {
    unoptimized: true,
    remotePatterns: [{ protocol: "https", hostname: "img.mobilecasualgames.com" }],
  },
  trailingSlash: false,
};

With static export I gave up API routes, ISR, middleware, and server-side image optimization. The level data comes from Neon, but only at build time: a script dumps it to src/data/levels.json, and the pages import that file. The same JSON feeds the client-side filter and the sitemap generator, so the site cannot disagree with itself.

That part worked. The two problems below did not show up in a normal browser test.

The og:url that pointed at the homepage

The first version of app/layout.tsx had this:

openGraph: {
  url: SITE_ORIGIN,
  siteName: SITE_NAME,
  title: "...",
  description: "...",
}

I assumed a level page that set its own openGraph.title and openGraph.description would replace the layout's openGraph object. Next.js merges metadata field by field. The page kept its own title, description, and image, and inherited url: "https://sand-blocks.org" from the layout. Every level page told social crawlers it was the homepage.

I found it with curl and grep, not with a browser. The canonical link was right. The og:url was wrong. Nothing looked broken in dev tools, and the page rendered fine, so it could have sat there for months.

The fix was to remove url from the layout entirely and set it only on pages that need it:

// app/levels/[id]/page.tsx
openGraph: {
  url: absoluteUrl(`/levels/${level.id}`),
  // title, description, image, ...
}

metadataBase handles relative URLs for canonical and images, but it does not fill in og:url. If you use a shared layout, check a deep page's rendered head before you trust it.

The default level list that was not in the HTML

The /levels page has a search box and pagination. My first version put the whole browser in a client component and read useSearchParams() to get ?q= and ?page=. During static export, Next.js skipped prerendering that subtree. The exported HTML had the page shell and nothing else: no level links, no range links. A crawler that does not run JavaScript saw an empty page.

This one is easy to miss because the site works in a browser. React hydrates, the client component renders, and the list appears. You have to curl the exported HTML or disable JavaScript to see the hole.

The fix was to split the page into two layers. The server component renders the default view, including the range navigation and the first 40 level cards. The client component only takes over when the URL has filter state.

// app/levels/page.tsx (server component)
<div id="levels-default-view">
  <LevelsControls ... />
  <LevelsGrid items={allLevels.slice(0, PAGE_SIZE)} />
  <LevelsPagination ... />
</div>

<Suspense fallback={null}>
  <LevelsBrowser />
</Suspense>

"use client";

export default function LevelsBrowser() {
  const searchParams = useSearchParams();
  const q = searchParams.get("q") ?? "";
  const page = Math.max(1, Number(searchParams.get("page") ?? "1"));
  const active = Boolean(q) || page > 1;

  useEffect(() => {
    const el = document.getElementById("levels-default-view");
    if (el) el.hidden = active;
  }, [active]);

  if (!active) return null;

  // Filter the bundled levels.json and render the result.
}

With no query string, the client component returns null and the exported HTML stays visible. With ?q=level 275 or ?page=4, it hides the default view and renders the filtered list from the same JSON. The default view is not wrapped in the client boundary, so it survives the export.

I also moved the range navigation out of the client component. It used to render only after hydration, which meant the links between the 40-level range pages were missing from the HTML. Now those links are in the server-rendered part, and each range page gets a real link from the hub.

Sitemap generation with a merge step

The sitemap script rebuilds the URLs it owns: static pages, level pages, range hubs, author pages, blog posts. It parses the existing sitemap first and keeps anything it does not recognize. That sounds fussy until you have hand-added a landing page and watched a generator delete it on the next run.

After a deploy I run a small IndexNow script that reads the sitemap and pings Bing, Yandex, Seznam, and Naver. Google finds pages on its own schedule. For a site that grows by adding level pages, the nudge is worth the two minutes.

What the tradeoff looks like

Static export is not free. There are no API routes, no incremental regeneration, no middleware, and no server-side image resizing. Level thumbnails are pre-sized WebP files on Cloudflare R2. The search is a client-side filter over a JSON file. The 404 is a static page. The production deploy is a directory of HTML, CSS, JS, and images served by a Cloudflare Worker with an assets binding.

For this site, that is a good trade. The content changes at human speed, and the pages are read far more than they are written. There is no per-user state. The build takes longer than a server-rendered deploy would, and I am fine with that.

If you are building something similar, the two checks I would run first are: curl a deep page and read the head, then look at the exported HTML with JavaScript disabled. Both bugs above passed a normal browser test.

The site is at https://sand-blocks.org/.

Syncing level data from seven games into a static Next.js site

Focss — Mon, 12 Oct 2026 12:21:57 +0000

Mobile Casual Games is a guide hub for puzzle games. It currently covers seven of them, and the level rows behind those guides add up to just over 8,000. New walkthroughs keep landing in the database, so the data moves constantly. The site itself is an output: "export" Next.js build: no runtime API, no database connection, nothing fetched when a visitor loads a page. Every level list, every range page, every redirect was decided at build time from JSON files that live in the repository.

That raises a practical question: when the data keeps changing, how does it get from wherever it was produced into a static bundle without anything breaking in between? This is how the pipeline works.

Where the rows come from

The source of truth is a Neon Postgres database with two tables. games holds store metadata: name, developer, icon URL, Play Store link, rating, install count. game_levels holds one row per level:

game_name | level | title | video_id | watch_url | img_url | created_at

video_id is a YouTube id, watch_url the matching watch link, img_url the cover thumbnail we uploaded to our own image host. Getting rows into that database is a separate job per game. For Food Hunt, our capture pipeline downloads each walkthrough video, extracts the cover frame, and uploads it to Cloudflare R2, so the site never hotlinks. For another game the source was someone's WordPress walkthrough site, which exposed the native REST API. A small Python script (scraper/scrape_game.py) walks the sitemap, filters slugs by a per-game prefix, and pulls clean JSON in batches of 50 slugs per request. It writes both JSON and CSV. The REST API turned out to be the right call there: the cached HTML pages had ad blocks injected into the body, and parsing around them would have been fragile.

Whatever the source, once the rows are in Postgres the web repository stops caring about them until it needs a fresh copy.

Two sync scripts, because history

There are two download scripts, which looks redundant until you see which files each one owns.

node scripts/download-data.mjs                       # games.json + levels.json
node scripts/download-levels.mjs rotaterings meowdoku # src/data/levels/<game>.json

download-data.mjs is the original. It was written when the hub was a single-game site for Food Hunt, and it still writes those two legacy files: every game row into games.json, and the full Food Hunt level list into levels.json, mapped to the shape the page components render.

download-levels.mjs is the multi-game sibling. You pass it one or more game names and it rewrites src/data/levels/<game>.json, one snapshot per game. Everything newer reads from these files: level counts, the 1-100 style range pages, the Level Guide in the navigation, the sitemaps, and, for the two games without a dedicated site, the level pages themselves.

Both scripts do the same three things beyond the query itself:

// Force IPv4 first - Neon is fronted by Cloudflare and returns both A and
// AAAA records; some sandboxes/serverless runtimes can't route IPv6.
dns.setDefaultResultOrder("ipv4first");

// env resolution: real environment first, then --env-file, then ./.env
const sql = postgres(rawUrl, { connect_timeout: 15 });

and they write the snapshot with a small envelope:

{
  "game": "rotaterings",
  "updatedAt": "2026-10-12T03:26:45.530Z",
  "count": 170,
  "levels": [
    {
      "id": 1,
      "name": "Level 1",
      "image": "https://img.mobilecasualgames.com/rotaterings/level-1.webp",
      "videoId": "...",
      "embedUrl": "https://www.youtube.com/embed/...",
      "watchUrl": "https://www.youtube.com/watch?v=...",
      "difficulty": "Beginner",
      "publishDate": "2026-10-12"
    }
  ]
}

updatedAt and count make the git diff readable. When you commit a refreshed snapshot, the diff header tells you which game was re-pulled and roughly how much moved, without opening the file. If a query returns zero rows the script warns and skips instead of writing an empty snapshot, so a typo in the game name cannot quietly erase 1,400 levels.

Reading the snapshots at build time

src/data/games.ts is the registry. Each snapshot is a static import, and each game is one entry with its display metadata, a theme color, and the level data attached:

import rotateringsLevels from "@/data/levels/rotaterings.json";

export const GAMES: GameEntry[] = [
  {
    game_name: "rotaterings",
    shortTitle: "Rotate Rings",
    themeColor: "#2eaae4",
    // no levelUrlPrefix - the hub hosts this game's level pages itself
    levels: (rotateringsLevels as { levels: StoredLevel[] }).levels,
  },
  // ...six more
];

The levelUrlPrefix field decides where a game's level detail pages live. Five of the seven games have their own guide site, so on the hub /<game>/<id> is a 301 to https://that-site/levels/<id> and the hub only renders lists. Smash Fest and Rotate Rings have no dedicated site, so the hub renders their pages directly.

Above the registry, src/data/levels.ts is a plain accessor module: fetchLevels, getLevel, getLevelIds, getMaxLevel, getFeaturedLevels. Every function takes a gameName as its first argument and resolves it through the registry, so the same code serves all seven games and nothing in the page components knows or cares which snapshot a number came from.

One detail worth copying: difficulty is recomputed on read, not trusted from the file.

function asLevel(l: StoredLevel): Level {
  return {
    ...
    difficulty: difficultyFor(l.id),  // thresholds live in src/lib/types.ts
  };
}

The snapshots were produced by different scripts at different times, and those scripts used different thresholds (the old single-game script bucketed at 100/250/400, the multi-game one at 100/500/1500). Deriving the value from the level number at render time makes the stored field meaningless, which means the snapshots no longer have to agree with anything. The same idea holds for the database: created_at is repurposed as the video publish date for structured data, because it is the only date the table carries.

When the database lags behind

Rows sometimes exist before they are inserted into Postgres, right after a fresh scraping run. There are two side doors for that case. import-levels-from-csv.mjs takes the same CSV the scraper produces and writes the identical <game>.json snapshot, using the same row-to-level mapping. build-data.py is the older door: it generated the original Food Hunt snapshots straight from the capture pipeline's output directory. Both exist so a snapshot can be regenerated from whatever artifact currently has the data, and the registry cannot tell the difference.

Derived files, regenerated on every build

The snapshots feed three derived outputs, all produced before next build runs.

Redirects. generate-redirects.mjs reads the levelUrlPrefix values straight out of games.ts and writes the per-game block in public/_redirects. One rule per game, not per level:

/foodhunt/1-100   /foodhunt/1-100   200
/foodhunt/*       https://food-hunt.org/levels/:splat   301

The splat is one rule because Cloudflare Pages caps a project at 2,100 redirects, and Pixel Flow alone has 2,089 levels. A per-level rule set would not fit, and it would need regenerating every time the game shipped a new batch. The self-rewrites for the block pages (/foodhunt/1-100 stays on the hub) are listed before the catch-all so the splat cannot swallow them. The same script handles the blog-to-level redirect for walkthrough articles, since a guide with level: 7 in its front matter renders on the level page, not at its old /blog/<slug> URL.

Guide badges. <LevelCard /> is a client component, and it needs to know which levels have a written guide. The markdown sources live server-side (content/blog/*.md front matter plus src/data/blog.ts, which imports node:fs), so generate-guide-levels.mjs scans them before each dev server or build and writes a tiny guide-levels.json. The client component reads that. Adding a guide stays a one-file change in content/blog/.

Sitemaps. generate-seo.mjs builds URLs from the registry and the snapshots. Since the five games with dedicated sites keep their level pages elsewhere, the main sitemap carries the hub's own pages plus the range blocks, and the two hub-hosted games get their own sitemap files (smashfestlevel.xml, rotateringslevel.xml) so a thousand-plus level URLs do not bury everything else.

Bundling limits

Static imports of 8,000 rows are server-side only, and the design keeps them there. toGameCard() strips every field except name, icon, rating, and levelCount: game.levels.length, which is all a card renders. The navigation's Level Guide receives a compact index per game (min, max, and the array of missing ids) instead of the id list. A browser that opens the level picker learns which numbers exist without downloading eight thousand objects, and the full snapshots never enter a client chunk.

Adding the eighth game

The whole point of the arrangement shows up here. A new game needs its rows in the database (or a CSV), one run of download-levels.mjs <game> to write the snapshot, one entry in games.ts, and nothing else. Range pages, counts, nav menu, redirects or hosted pages, sitemaps, and the build all follow from those two artifacts, and every step leaves a reviewable diff in git.

You can see the result at mobilecasualgames.com, and the pipeline described here is what keeps its seven level databases in one repository, refreshed with a single command and a commit.

How 913 Puzzles Became 7,304 Levels: Procedural Variation on a Precomputed Puzzle Bank

Focss — Sun, 04 Oct 2026 03:26:01 +0000

Meowdoku ships over a hundred levels and keeps growing. Every one of them has to be provably solvable. This is a Star Battle-style puzzle, so a malformed board is a dead end the player can't solve.

You can either generate levels at runtime with a solver or hand-author them. Neither works well in practice. Runtime generation puts a backtracking search on the critical path of a player tapping "Next." Hand-authoring doesn't scale past a few dozen boards.

What we ended up doing: store a finite bank of verified puzzles, and derive variation from geometry instead of content.

The data shape

A bank is a JSON dictionary of difficulty tiers. Each entry is small: a region map and a solution.

{
  "1": [
    {
      "seed": 7,
      "regionMap": [[3,3,0,3],[1,3,3,3],[3,3,2,2],[3,3,3,2]],
      "solution": [2,0,3,1],
      "r": 1,
      "steps": 4
    }
  ]
}

regionMap[r][c] is the color-region index of each cell. solution is stored compactly: one column index per row, not a 2D grid. Since the rules guarantee exactly one cat per row, solution[r] = c fully describes the answer in n numbers instead of n².

That's compact for storage, but it doesn't give you a shape you can rotate. You can't rotate an array of row indices; the shape isn't there.

Picking a level is a pure function

Level selection depends only on the level number, which is what lets the server reproduce the same board:

const index = (levelNum - 1) % rawList.length;
const transform = ((levelNum - 1) * 3) % 8;  // 4 rotations × 2 reflections

index walks the bank; transform picks one of eight symmetries of a square: four rotations, optionally mirrored. Because rotation and reflection preserve the puzzle's constraints, a solved puzzle stays solved under any transform. So the player doesn't see "the same puzzle again," they see a different board that happens to share a skeleton.

Multiplying that out: the 6×6 bank holds 913 entries, which becomes 7,304 distinct boards.

The transform, and the shape problem

The transform itself has one awkward step:

export function transformPuzzle(regionMap: number[][], solution: number[], transform: number) {
  const size = regionMap.length;
  if (transform === 0) return { regionMap, solution };

  // The stored solution is row → col, which isn't a rotatable shape.
  // Rebuild it as a 2D boolean grid first.
  const catGrid = Array.from({ length: size }, () => Array(size).fill(false));
  for (let r = 0; r < size; r++) catGrid[r][solution[r]] = true;

  let newMap = regionMap.map(row => [...row]);
  let newCats = catGrid.map(row => [...row]);

  for (let step = 0; step < transform % 4; step++) {
    const rotatedMap  = Array.from({ length: size }, () => Array(size).fill(0));
    const rotatedCats = Array.from({ length: size }, () => Array(size).fill(false));
    for (let r = 0; r < size; r++) {
      for (let c = 0; c < size; c++) {
        rotatedMap[c][size - 1 - r]  = newMap[r][c];      // 90° clockwise
        rotatedCats[c][size - 1 - r] = newCats[r][c];
      }
    }
    newMap = rotatedMap;
    newCats = rotatedCats;
  }

  if (transform >= 4) {                                  // then mirror horizontally
    for (let r = 0; r < size; r++) { newMap[r].reverse(); newCats[r].reverse(); }
  }

  // Collapse the boolean grid back into the compact row → col form
  const newSolution = new Array(size).fill(-1);
  for (let r = 0; r < size; r++) {
    for (let c = 0; c < size; c++) if (newCats[r][c]) { newSolution[r] = c; break; }
  }

  return { regionMap: newMap, solution: newSolution };
}

One thing to remember: compact storage formats and geometric operations rarely mix. Expanding to a 2D grid, doing both operations there, and collapsing back at the end is clearer and less bug-prone than trying to shortcut the conversion.

The same function runs on the server

The server can compute the exact board the client is playing, because level selection is pure. It loads the same bank file, caches it in memory, and re-runs the rules to validate a claimed solution:

// src/lib/serverLevelValidator.ts
for (const cat of cats) {
  if (rowSet.has(cat.r))     return { valid: false, reason: `Multiple cats in row ${cat.r}` };
  if (colSet.has(cat.c))     return { valid: false, reason: `Multiple cats in col ${cat.c}` };
  const region = regionMap[cat.r][cat.c];
  if (regionSet.has(region)) return { valid: false, reason: `Multiple cats in region ${region}` };
  rowSet.add(cat.r); colSet.add(cat.c); regionSet.add(region);
}

So the server can derive the board from the level number alone. No board state has to be transmitted, stored, or trusted. The same property also powers the daily challenge, which hashes the UTC date string into an (index, transform) pair so every player worldwide gets an identical puzzle with zero server-side scheduling.

What it costs

There are trade-offs:

Bank size. The level data is ~67 MB of JSON across 34 files. That's a significant payload, which is why banks are split by grid size and variant type, fetched on demand, and served with Cache-Control: immutable.
Memory. A client-side Map cache holds preloaded levels, and we keep it bounded by only preloading the next five levels. On the server, the same cache is fine because the working set is a handful of files.
A solver you still trust. The bank is the thing you verified once. If a bad puzzle ever gets in, transforms will faithfully replicate it eight ways.

The takeaway

Precomputing correctness once and varying the geometry is what made this scale. The bank stays small, and the player still sees a new board every level.

Play it here: https://meowdokuguide.com/online

YouTube Playlist to a 100% Static

Focss — Tue, 18 Aug 2026 06:55:04 +0000

Every so often you find a mobile game you enjoy but can't finish. Food Hunt is one of those match-3-style puzzle games where you clear colored tiles by tapping — and the difficulty climbs fast. The content lives on YouTube as a long playlist of level-by-level walkthrough videos, one video per level, each titled Food Hunt level N walkthrough solution.

I wanted to turn that playlist into a proper website: a place where players can search, filter, and jump straight to the exact level they're stuck on, with an embedded video, a difficulty label, and even adjacent-level navigation.

What I didn't want: a slow CMS, a monthly server bill, or a fragile scraper that breaks every time a video title changes.

The result is Food Hunt — a site serving 585 level pages, generated entirely at build time, deployed on Cloudflare's edge, with content refreshed weekly by an automated pipeline. No web server, no runtime database connection, no per-page API calls.

Here's the full technical breakdown: the data pipeline, the static frontend, and the SEO machinery — including the patterns I'd reuse (or avoid) next time.

System architecture

flowchart LR
    YT[YouTube Playlist<br/>Food Hunt level N walkthrough] --> CRAWL[yt-dlp<br/>extract_flat metadata]
    CRAWL --> VIDEO[JSON: video links + level numbers<br/>regex-parsed from titles]
    VIDEO --> THUMB[Thumbnail download<br/>i.ytimg.com, concurrent]
    THUMB --> WEBP[Pillow → WebP]
    WEBP --> R2[Cloudflare R2<br/>img.mobilecasualgames.com]
    CRAWL --> DB[(Neon Postgres<br/>serverless)]
    DB --> SNAP[Build-time snapshot<br/>download-data.mjs → JSON]
    SNAP --> NEXT[Next.js static export<br/>generateStaticParams]
    NEXT --> SEO[sitemap.xml + robots.txt<br/>IndexNow submission]
    SEO --> PAGES[Cloudflare Pages<br/>global edge]
    PAGES --> USR[Visitors]
    R2 --> USR

The whole thing is a one-way data flow:

Python pipeline (runs weekly) pulls the YouTube playlist, parses it, downloads thumbnails, uploads them to R2, and upserts records into Neon.
Build step (runs on deploy) downloads the database into local JSON snapshots.
Next.js statically generates every page from those snapshots and emits sitemaps.
Cloudflare Pages serves the exported out/ directory from the edge.

Let me walk through each layer.

Part 1: The data pipeline (Python)

The source of truth is a YouTube playlist. I used yt-dlp with extract_flat — which returns playlist metadata without downloading any video, making it fast and cheap:

ydl_opts = {"quiet": True, "no_warnings": True, "extract_flat": "in_playlist"}
with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    data = ydl.extract_info(config.PLAYLIST_URL, download=False)

Parsing structure from video titles

The playlist is a flat list of videos; the only structure is encoded in the titles (Food Hunt level 1, Food Hunt level 2, ...). So the "schema" is a pair of regexes. I classify every entry into three buckets — single level, level range, or unknown:

def parse_entry(title):
    """Returns (kind, level_or_None, start_or_None, end_or_None)"""
    t = title or ""
    m = re.search(config.RANGE_REGEX, t, re.IGNORECASE)
    if m:
        return "range", None, int(m.group(1)), int(m.group(2))
    m = re.search(config.LEVEL_REGEX, t, re.IGNORECASE)
    if m:
        return "single", int(m.group(1)), None, None
    return "unknown", None, None, None

Two details worth copying:

unknown is a first-class bucket. Unparseable titles (private videos, renamed videos) don't crash the pipeline — they land in a report you can eyeball.
Video IDs are extracted defensively from multiple URL formats (?v=, youtu.be/, /embed/), because playlist entries don't always use the same URL shape.

Thumbnails: concurrent download + WebP

Each level page needs an image. YouTube serves thumbnails at i.ytimg.com/vi/<id>/..., so I download them concurrently with a ThreadPoolExecutor, then convert everything to WebP with Pillow:

from concurrent.futures import ThreadPoolExecutor, as_completed

with ThreadPoolExecutor(max_workers=8) as pool:
    futures = {pool.submit(fetch_one, v): v for v in videos}
    for fut in as_completed(futures):
        # save {index:03d}_{video_id}.png → .webp

Why WebP? It's typically 25–35% smaller than PNG for these screenshot-style thumbnails, and the site is configured to only emit WebP anyway.

Storage: Cloudflare R2 + Neon Postgres

Two storage targets, two very different access patterns:

Images → Cloudflare R2. Uploaded with boto3 (R2 speaks the S3 API), and served through the CDN domain img.mobilecasualgames.com. The upload step is idempotent: it skips objects that already exist, so re-running the pipeline never re-uploads 585 images.
Records → Neon. A serverless Postgres database accessed with psycopg2. There are three tables: games (game metadata), game_levels (one row per level + video), and game_guides (auto-generated walkthrough text + FAQ content).

The pattern that saved me: incremental merge

The pipeline's most important rule is:

Existing levels are never overwritten. Only missing levels are added.

The script reads the levels already in the database, then upserts only the ones that don't exist yet:

existing = sn.read_existing_levels(game_name)   # from Neon
missing = [lv for lv in parsed_levels if lv["level"] not in existing]

for level in missing:
    sn.upsert_level(game_name, level)           # INSERT ... ON CONFLICT DO NOTHING

Why does this matter?

Video titles occasionally change or get removed. Re-running the crawl must not silently clobber a previously correct record.
The YouTube playlist is append-only in practice — new levels get added at the end. So the diff is almost always new_levels = all_levels - existing, which is exactly the merge behavior you want.
It makes the pipeline safe to run weekly, unattended, which is what the automation is built for.

Automation

Everything above runs on a schedule (a weekly cron in my case): crawl → download → integrate → rebuild the site. Because each step is idempotent and produces a JSON report, a failed run can be re-run without any manual cleanup.

Part 2: The frontend (Next.js)

The site itself is deliberately boring in the best way. Next.js 14 (App Router) + TypeScript + Tailwind CSS, with one crucial setting:

// next.config.mjs
const nextConfig = {
  output: "export",      // no Node server — emit pure static HTML
  images: {
    unoptimized: true,   // static export can't use the image optimizer at runtime
    formats: ["image/webp"],
  },
};

Build-time data, not runtime data

There is no database connection and no API at runtime. Instead, a small script (download-data.mjs, using the postgres package) pulls the whole dataset from Neon into versioned JSON snapshots:

src/data/
├── games.json     # game metadata
└── levels.json    # 585 levels: id, name, image, videoId, embedUrl, watchUrl

Then the data layer (levels.ts) reads those JSON files directly. This is the key trade-off: you trade real-time data for zero runtime cost and instant scaling. For a walkthrough site that updates weekly, that's the right trade.

A nice side effect: the data snapshot lives in the repo, so deploys are reproducible and the build fails loudly if the data is malformed.

One static page per level

Every level gets its own URL (/levels/1, /levels/2, ...) via generateStaticParams, and its own <head> via generateMetadata:

export function generateStaticParams() {
  return levelsData.levels.map((l) => ({ id: String(l.id) }));
}

export async function generateMetadata({ params }) {
  const level = await getLevel(Number((await params).id));
  return {
    title: `Food Hunt ${level.name} Walkthrough`,
    description: `Watch the full video walkthrough for ${level.name}. ${level.difficulty} strategy...`,
    alternates: { canonical: `/levels/${level.id}` },
    openGraph: {
      type: "video.other",
      url: absoluteUrl(`/levels/${level.id}`),
      videos: [{ url: level.watchUrl, type: "text/html", width: 1280, height: 720 }],
    },
    twitter: { card: "summary_large_image", images: [level.image] },
  };
}

Because output: "export" produces plain HTML files, every one of the 585 pages is a crawlable, indexable, fast-loading static document — no client-side rendering wall between Googlebot and the content.

A few component-level details I'm happy with:

YouTubeEmbed — a wrapper around the standard iframe embed, with lazy loading and a consistent 16:9 aspect ratio.
LevelsBrowser — a client component that does search + difficulty filter + pagination entirely in the browser over the preloaded JSON.
Adjacent-level navigation — every level page links to the previous/next level, which is both good UX and good internal linking for SEO.

Part 3: SEO & operations

For a content site whose entire purpose is being found on Google for queries like "food hunt level 240 walkthrough", SEO isn't an afterthought — it's the product.

sitemap.xml: generated, but never destructive

sitemap.xml is generated from the data snapshot — but with a merge rule I wish more tools had:

Static pages (/, /levels, /download) and level pages (/levels/\d+) are regenerated from the data.
Everything else (blog posts, custom landing pages) is preserved verbatim from the existing sitemap.

// generate-seo.mjs (simplified)
const existing = parseExistingSitemap("public/sitemap.xml");
const staticUrls = buildStaticUrls();          // from levels.json
const customUrls = existing.filter(u => !isStaticOrLevel(u));
const merged = [...staticUrls, ...customUrls];
writeSitemap(merged);

This means the sitemap script is safe to run on every deploy — it will never wipe out manually added URLs. That's the same philosophy as the database merge, applied one layer up.

robots.txt + IndexNow

robots.txt is generated alongside the sitemap into public/.
After each deploy, an IndexNow submission script pings search engines (Bing, Yandex) with the updated URL list, so new levels get indexed quickly instead of waiting for the next natural crawl.

Deployment: Cloudflare Pages

With output: "export", the out/ directory is a fully static site. Deploying is just a matter of pointing Cloudflare Pages at it:

// wrangler.jsonc
{
  "name": "foodhunt",
  "assets": { "directory": "./out", "not_found_handling": "404-page" }
}

You get global CDN caching, HTTPS, and zero infrastructure to maintain — the site is just files.

What I'd do differently next time

A few honest takeaways from building this:

Don't trust playlist order. I initially assumed playlist order == level order. It isn't always — the regex-parsed level number is the only reliable key. Always parse and validate.
Idempotency is non-negotiable for automation. Every step (download, upload, upsert, sitemap) must be safe to run twice. This single property is what makes unattended weekly runs possible.
Static export changes image strategy. With output: "export" you lose next/image's on-demand optimizer, so pre-optimizing to WebP in the pipeline was the right call — do image optimization upstream, not at runtime.
Metadata is code, treat it that way. Per-page generateMetadata gives you canonical URLs, Open Graph video cards, and Twitter cards for free — it's the highest-leverage SEO work in a Next.js project.

Try it out

If you're stuck on a level of Food Hunt (or just curious to see 585 static pages in the wild), check out food-hunt.org — search for your level, watch the walkthrough, and move on.

The stack in one line: Python + yt-dlp → Cloudflare R2 + Neon Postgres → Next.js static export → Cloudflare Pages, held together by idempotent, incremental, fully automated data flows.

If you're building something similar — a content site from a semi-structured source — I hope the merge-don't-overwrite pattern and the build-time-snapshot trick save you a few late nights.

Finding Pixel Flow levels with a 768-bit RGB pHash visual search

Focss — Thu, 02 Apr 2026 06:47:36 +0000

I’m a big fan of the game Pixel Flow, but I often find myself getting completely stuck on specific levels. Because it is a purely visual grid game, you cannot simply search for a solution using text. To solve this, I built a reverse image search engine specifically designed to find level solutions based on a screenshot.

The challenge was figuring out how to do image matching quickly, accurately, and without heavy infrastructure. Here is how I approached the technical side:

Multi-Channel pHash (Per-Channel RGB)
Most perceptual hashing (pHash) implementations convert an image to grayscale before processing. However, in a game like Pixel Flow, color is the primary piece of information. Discarding color would mean losing the ability to distinguish between levels with similar layouts but different color palettes.
To fix this, I split the image into its Red, Green, and Blue channels and computed a 256-bit pHash for each channel independently.
Combining into a 768-Bit Fingerprint
After generating a 256-bit hash for all 3 channels, I concatenated them. This creates a combined fingerprint of 768 bits (256 * 3). This captures both the structural layout and the color distribution of the game level perfectly.
Hexadecimal Compression
Storing and querying a raw 768-bit binary string isn't the most efficient approach for database queries. To reduce the data footprint, I convert the binary string into a hexadecimal string. This brings the size down to just 192 characters while retaining all the precision.
Fast Hamming Distance Matching
When a user uploads a screenshot, the system generates its 768-bit hash on the fly. It then compares this hash against the saved database of known level hashes. By calculating the Hamming distance (the number of positions at which the corresponding bits are different), it can rapidly find the closest match.
Displaying the Top 6 Matches
Finally, the system pulls the 6 records with the smallest Hamming distance and displays them to the user. Showing a small cluster of top matches instead of just one gives the user fallback options in case there are minor discrepancies due to image cropping, phone UI overlays, or screen dimming.

I'd love to hear your feedback on this! Are there more efficient ways to handle color-sensitive image hashing for grid-based games?

Link to the site: https://pixelflowonline.net/

From Zero to Ranked: Building a High-Performance NBA Player Randomizer with Next.js 14 & Cloudflare

Focss — Sun, 15 Feb 2026 02:47:35 +0000

As a developer and an NBA fan, I noticed a recurring problem in communities like r/NBA2K: players often get "choice paralysis" when starting a new MyLeague rebuild or a Blacktop 1v1 session. Static lists are boring, and existing randomizers are often cluttered with ads or lack specific filters.
I decided to build a high-performance solution: . Here’s how I leveraged Next.js 14 and Cloudflare to create a tool that is not only fast but also highly optimized for SEO.

1. The Stack: Why Next.js and Cloudflare?

For a tool-based website, performance is the primary SEO signal. I chose:

Next.js 14 (App Router): For its superior handling of Server Components and built-in Image Optimization.
Cloudflare Pages: To deploy at the edge, ensuring the generator loads instantly regardless of the user's location.
Tailwind CSS: For a "dark mode" aesthetic that resonates with the gaming community.

2. Data Strategy: JSON vs. CSV

While many data-heavy sites rely on databases, I opted for a JSON-driven architecture.
Performance: Next.js can import JSON files directly, allowing the JS engine to parse data with zero runtime overhead compared to CSV.
Filtering Logic: Storing player data in a structured JSON format allowed for instant client-side filtering by Team, Position, and Country without a single API call.

3. The Core Logic: Ensuring True Randomness

A common complaint with randomizers is "repetitive results." To ensure every player in the NBA database has an equal chance, I implemented the Fisher-Yates Shuffle algorithm.
This algorithm ensures an unbiased permutation of the player array.
When a user applies a filter—like "Center from France"—the tool first creates a filtered subset and then applies the shuffle to provide a fresh result every click.

4. SEO for Tools: Beyond the Meta Tag

Tools often suffer from "Thin Content" issues in the eyes of Google. To break into the first page of search results, I focused on:
Topical Authority: Instead of just a button, I added a comprehensive FAQ section explaining the tool's use cases for NBA 2K Challenges and Fantasy Basketball.
Dynamic Metadata: Each page uses Next.js 14’s generateMetadata to ensure that keywords like "Random NBA Team" and "2K26 Randomizer" are indexed correctly.
Internal Linking: I built a "Topic Cluster" by linking the main player generator to specialized tools like the NBA Team Generator.
Check out the live project here: https://randomnbaplayergenerator.net/

Random Nba Player Generator - A Free Tool

Focss — Wed, 04 Feb 2026 10:00:16 +0000

NBA Random Player Generator – What It Is

This free online tool instantly generates a NBA random player from both current and all-time rosters. Whether you're settling debates, playing fantasy games, or creating fun challenges, this generator gives you new players with every click.

How To Generate Random Nba Player

The Random NBA Player Generator works by leveraging a comprehensive database that includes detailed information on both current and historical NBA players. This database is meticulously compiled and regularly updated to ensure it encompasses a broad spectrum of players from different eras of the NBA. When a user interacts with the Random NBA Player Generator, the tool executes a randomized selection process.

Frequently Asked Questions

Is the Random NBA Players Generator free?

Yes, the Random NBA Player Generator is 100% free to use. Our mission is to provide a high-quality, accessible tool for the global basketball community. There are no hidden subscription fees, no "premium" tiers for specific teams, and no mandatory registration or login required. You can generate an unlimited number of players, experiment with all filtering combinations, and use the tool for your personal projects or gaming sessions without ever reaching for your wallet. We believe that the love for the game should be accessible to everyone, and this tool is our contribution to that vision.

Does it include current NBA players?

Yes, the generator includes active NBA players from recent seasons.

Can I use this tool for games or challenges?

Absolutely. Many users use it for NBA trivia, fantasy challenges, or social media content.

Is each result truly random?

Yes. Each click generates a new, random NBA player from the database.

Can I filter players by team or position?

Currently, the generator provides fully random results. Filters such as team, position, or era may be added in future updates.

Why would someone use a random NBA player generator?

People use random NBA player generators to discover new players, make unbiased selections, settle debates, or simply have fun with basketball-related challenges.

If you want to experience it, you can click on the link

https://randomnbaplayergenerator.net/