DEV Community: PHT

One link is all it takes: syncing bead patterns between phone and PC without a backend

PHT — Fri, 30 Oct 2026 10:12:09 +0000

A couple of weeks ago I wrote about my Perler bead pattern generator — a 100% client-side tool where the whole app plus your work exports as one self-contained HTML file.

That post ended with a problem I hadn't solved: people don't craft at one device.

They browse reference photos on the phone on the couch, but they build the actual board and print the pattern at a desk. My tool was web-only, and my users (mostly in China) increasingly asked for a WeChat mini program version. Building it was the easy part — the hard part was that once your pattern lived on the phone, it was stuck there.

The constraints make the design

The web tool has a hard rule I'm not willing to break: no accounts, no backend, nothing ever leaves the browser. Free tool + hobby crafters + uploaded family photos = cloud storage is a non-starter, both for trust and for my hosting budget.

So how do you move a pattern from a WeChat mini program to a PC browser with zero infrastructure?

❌ Accounts + cloud sync — violates the whole premise
❌ File export → send file → import — clumsy on mobile, and WeChat file handling is its own adventure
✅ A URL. The pattern IS the link.

The mini program copies a link to the clipboard; the user sends it to themselves (WeChat's File Transfer Assistant is made for this), opens it on the PC, and the pattern is just… there. Everyone already knows how to share a link.

Fitting a 4000-cell pattern into a URL

The format is versioned, dot-separated, and lives entirely in the URL fragment:

https://perler.phtbyte.com/#p=1.49.69.mard.H01-H02-H08-….zqn3zj01…
        └─┬─┘ ─┬─────────────────────────────┘
       version  payload

Why the fragment (#) and not a query string? Two reasons:

Fragments are never sent to the server. The pattern data exists only in the browser. No logging, no GDPR-adjacent questions, and my static host (GitHub Pages) doesn't need to care.
No practical length limit. Query strings start breaking things (proxies, analytics, some CDNs) around 2KB. Fragments just work — the browser never transmits them.

The payload itself:

Field	Meaning
`1`	Format version — so I can change the scheme later without breaking old links
`49.69`	Board width × height
`mard`	Palette ID (Perler / MARD / ARTKAL / YANT…)
`H01-H02-H08-…`	The code table: every bead color used, in order
`zqn3zj01…`	Run-length encoded grid

The code table — or, the bug I designed my way out of

My first instinct was to encode each cell as the palette index: one character in base36 covers values 0–35. Then I actually counted the MARD palette: 221 colors. Base36 dies at 36. A two-character index would have worked, but it bloats every single run.

The better move: put the used colors in a table up front and encode cells as table positions. A real pattern uses maybe 10–30 colors out of 221, so table positions fit in one base36 character with room to spare (the table caps at 34 — index 35 is reserved). Bonus: cell data now references semantic color codes, not positional indices, so palette data can evolve without invalidating old links.

The RLE run: 3 characters per run

Each run is exactly 3 chars: 1 char = table index (z = empty cell), 2 chars = run length in base36 (max zz = 1295).

// encode: row-major, runs of same color (or empty)
rle += ch + B36[Math.floor(run / 36)] + B36[run % 36];

A 49×69 board (3,381 cells) with ~15 colors lands around 500–800 characters of URL. Short enough to survive a clipboard round-trip through WeChat without anyone noticing.

Trust nothing: decoding defensively

A link can be mangled by any layer between the phone and the PC — truncated copy, URL shortener, autocorrect, a sibling editing the text for fun. The decoder validates everything and rejects instead of rendering something half-broken:

const parts = raw.split('.');
if (parts.length < 6 || parts[0] !== '1') return null;      // version
const pal = PALETTE_BY_ID[paletteId];
if (!w || !h || !pal || w * h > 40000) return null;         // sane geometry
for (const c of table)
  if (!pal.colors.some((cc) => cc.code === c)) return null; // real color code?
if (rle.length % 3 !== 0) return null;                      // well-formed runs
if (codes.length !== w * h) return null;                    // exact cell count

Every check is cheap; the alternative is a corrupted grid that a crafter discovers halfway through beading. A bad link gets a polite "invalid link" toast and the app stays untouched. Same philosophy as the single-file export: fail closed.

The payoff at the desk: a printable grid

Importing was half the feature. The other half is what you do once the pattern is on the big screen: print it. So I added a grid export — a proper work sheet, not a screenshot:

24px cells (halving automatically, down to the canvas cap of 4096px, so a 200-column monster still exports)
Bead codes printed in every cell, with the text color chosen per-cell by background luminance so it stays readable on both white and black beads
Gridlines at 1px opacity 0.16 — visible on paper, invisible in the colors
Done-marks: teal checkmarks on colors you've finished, matching the in-app tracker — print a fresh sheet and your progress carries over
A header with title, size, and palette name, because worksheets get stacked and shuffled

// text stays readable on any bead color
const lum = 0.299 * r + 0.587 * g + 0.114 * b;
x.fillStyle = lum > 150 ? '#333' : '#fff';
x.fillText(code, gx + cell / 2, gy + cell * 0.54);

The whole workflow now fits in one sentence: photo on the phone → pattern on the couch → link on the desk → print → iron some beads.

What I learned (again)

The humble URL is still the best state-transfer mechanism ever shipped. No SDK, no auth flow, no rate limits, works across apps that were never designed to talk to each other — a WeChat mini program and a static web page share data through something every chat app already knows how to carry.

If your app's state is small and user-owned, try making it a link before you build a sync service.

Try it: perler.phtbyte.com (works offline once loaded) · Source: github.com/pht1991/perler-blueprint (MIT) · On WeChat, search mini program 我要拼豆图纸 — patterns sync between the two via the link format above.

I built a Perler bead pattern generator that exports your work as a single HTML file

PHT — Thu, 29 Oct 2026 04:00:41 +0000

If you've never heard of Perler beads (fuse beads): you place tiny plastic beads on a pegged board, iron them, and they melt into pixel art you can keep. It's physical pixel art — and people make genuinely impressive stuff with it.

Planning a big project requires a pattern: a grid telling you which bead color goes in which cell. Existing online generators do the quantization for you, but I wanted one with a specific superpower: the whole tool, plus your current work, exportable as ONE self-contained HTML file you can keep, email, or open years later.

So I built Perler Bead Blueprint Maker — 100% client-side, no account, no backend, images never leave your browser. Source is on GitHub (MIT).

This post is about how it works and the one bug that taught me to never regex-replace HTML again.

TL;DR — what it does

Upload an image → quantized to real bead palettes (Perler, MARD, ARTKAL, YANT — including their actual color codes and names)
Preset sizes (29/38/49/69/104…) or any custom N×N
Color budget: k-means clustering in Lab space to hit "≤ 25 colors" without visual mush
Interactive 2D grid (bead codes printed in cells, highlight tracking, "done" marks that persist)
3D board view with real perler beads (Three.js InstancedMesh) and a depth-layering mode that stacks the board into relief layers
Editing tools: brush / fill / eraser / eyedropper with undo history
Export: poster PNG/PDF, multi-size PDF collection + CSV shopping list, and — the reason this project exists — a single HTML file that IS the app WITH your work inside

The quantization: Lab space + seeded k-means

Naive RGB distance quantizes badly (blues and purples especially). Everything runs in CIELAB and uses ΔE76 for matching:

// rgb → Lab, then nearest palette color by ΔE76
function nearest(hex: string, palette: Color[]): Color {
  const [L, a, b] = rgb2lab(hex);
  let best = palette[0], bestD = Infinity;
  for (const c of palette) {
    const d = deltaE76(L, a, b, c.lab);
    if (d < bestD) { bestD = d; best = c; }
  }
  return best;
}

For the color budget, a palette of 221 colors reduced to "25 colors max" is a clustering problem. k-means++ in Lab space works well, with one addition: a fixed seed, so the same image always quantizes to the same pattern. Sounds obvious, but most generators re-roll the dice on every page load — you refresh and your carefully-tuned 20-color selection becomes 23 different colors.

The 3D board

Beads are InstancedMesh cylinders — one draw call for thousands of beads — with a canvas-generated texture that fakes the hole. The pegboard underneath has bumps. Nothing fancy, but it sells the illusion:

const geo = new THREE.CylinderGeometry(0.42, 0.42, 0.32, 24);
const mesh = new THREE.InstancedMesh(geo, mat, count);
// one setMatrixAt per bead, y offset = board layer

The depth-layering mode is my favorite: a heuristic (brightness + center weighting + smoothing, then equal-frequency bucketing into 7 layers) turns a flat pattern into stacked relief layers — for making actual 3D bead sculptures, shakelight-style.

The single-file export (and the bug that broke it)

The exported file is the entire app bundle + your current state (blueprint, progress, source image as a compressed data URL) embedded in a <script type="application/json"> tag. On open, the app checks that tag, restores state into localStorage, and you continue where you left off. No server, no database — the file is the database.

My first implementation did the injection with a regex:

// ❌ DO NOT DO THIS
html = html.replace(
  /<script id="perlerSaved"[^>]*>[\s\S]*?<\/script>/,
  `<script id="perlerSaved">${json}</script>`
);

It worked… until it didn't. The check I skipped: the marker string perlerSaved also exists inside the bundled JS — in the very restore code that reads the tag, and inside minified variable-containing chunks. The regex matched there first, and replaced ~84KB of application code with a JSON blob. The exported file opened to a white screen.

Two lessons, now burned into the project's docs:

// ✅ DOM-based injection: the parser finds THE element, not any text occurrence
const tpl = document.createElement('div');
tpl.innerHTML = html;
const tag = tpl.querySelector('#perlerSaved');
tag.textContent = json;          // textContent never executes, never mis-matches
html = '<!DOCTYPE html>' + tpl.innerHTML;

Never regex-replace structured markup. Parse, query, mutate, serialize. The regex version produced a file that worked exactly once — when I tested it before the bundle contained the string, and never again.
Test the export against the real production bundle, not a dev build. Dev bundles don't contain minified code that collides with your markers.

Bonus property of this design: the exported file strips external <script src> tags, so your exported copy has no analytics, no external requests — it works offline forever.

Small things that mattered more than expected

Printing bead codes inside grid cells came from a single user comment ("no way to know which color goes where without cross-checking the list"). Cells auto-hide codes below ~13px, and text color flips black/white by cell luminance with a contrast outline.
Language toggle (中文/EN) — first-use detection from navigator.language, persisted choice. A pixel-art tool is visual, but "MARD 221" labels and toasts still need to be readable.
Pointer Events everywhere — one code path for mouse and touch, pinch-zoom included. Writing mouse + touch handlers separately in 2026 is self-harm.
Privacy-friendly analytics: GoatCounter, no cookies, event names like e/upload/104/mard48/zh/m (event/size/palette/language/device). One gotcha I hit the hard way: GoatCounter silently classifies traffic from cloud-provider IP ranges as bots — if you test your own site through a VPN/proxy, your dashboard stays at zero and nothing tells you why.

Try it

Live: https://perler.phtbyte.com/
Source: https://github.com/pht1991/perler-blueprint

Everything runs locally; upload an image, hit the 3D view, and export a single file as a souvenir.

If you build something with a pattern from it (or find a quantization case where it picks a clearly wrong color), I'd genuinely like to hear about it in the comments.

COCOS 4 Is Open Source — But Is It Time to Leave Cocos Creator 3.8?

PHT — Tue, 13 Oct 2026 03:51:19 +0000

description: "COCOS 4 went fully open source under MIT in early 2026. I run a Cocos Creator 3.8 mini-game in production — here's my honest call on whether to migrate, and what actually changed."

Cross-post note: This is the original article from my blog, Indie Game Lab. Read it there for the properly styled version, or keep reading here — it's identical.

TL;DR: I run a Cocos Creator 3.8 WeChat mini-game in production. COCOS 4 — fully open-sourced under MIT in early 2026 — is the biggest shift in the Cocos ecosystem in years, but it is not a "drop 3.8 now" signal, especially for mini-game developers. The engine and editor have been split apart (the new IDE is called PinK), WeChat support is rolling out gradually, and 3.8 is still the more stable bet for my use case. Here's the honest breakdown and the call I'm making.

1. The headline: what actually shipped

Cocos was acquired by the Chinese gamification company SUD for around $72M in November 2025. On January 5, 2026, SUD announced that COCOS 4 is fully open source under the standard MIT license — every commercial clause from the old Cocos Creator has been removed. The public repositories include the engine core (github.com/cocos/cocos4), the cross-platform code, the cocos-cli, and a full headless IDE mode. There is no commercialization target behind it; SUD's stated motive is reaching more developers and feeding more game content into its own ecosystem.

For a solo dev, "MIT, no strings" is a genuinely big deal. But the headlines skipped the part that actually affects your day-to-day: this isn't a normal version bump.

2. The part that confuses everyone: it's not "Cocos Creator 4"

Through versions 1.x, 2.x, and 3.x, "Cocos Creator" meant one thing: the engine and the editor bundled together. COCOS 4 breaks that apart:

COCOS = the engine only (version 4 is just the latest release number).
PinK = the new standalone IDE. The visual editing features from Cocos Creator migrate here over time.
cocos-cli = headless mode. Core editing functions move to CLI-accessible headless operations that become part of the engine core.

So when you search "Cocos Creator 4," what you actually mean is COCOS 4 (engine) + PinK (IDE). Same lineage, different packaging. If you're evaluating it, search "COCOS 4" — you'll find the right repos and docs.

The brand rename is the surface change. The structural one is engine/editor separation.

3. What changed that a solo dev actually cares about

MIT, no commercial clauses. You can read, patch, and even fork the engine into your own modified build. For a one-person team that's been burned by licensing surprises elsewhere, this removes a whole class of risk.
AI-native by design. JavaScript and TypeScript stay the primary languages, and new capabilities are delivered as MCPs or Agents rather than traditional libraries — UI components, for example, ship as fully deliverable Agents, not call-and-use widgets.
Lighter and more modular. The stated goal is "faster, smaller, more efficient," meant to run on any device with a screen.
Cross-platform, but read the fine print. Native platforms are covered across the board; mini-game platform support rolls out gradually, and Steam-class native targets are on the roadmap.
Forward compatibility. COCOS 4 is an evolution of 3.x, follows SemVer, and keeps a minimum six-month deprecate-to-remove window.

4. What it means for a solo indie

The upside is real:

Zero licensing anxiety, forever.
You can fix engine bugs yourself instead of waiting on a vendor.
An open PR flywheel — more contributors, faster fixes.
AI-tooling that actually understands the engine because the source is open.

But the open questions matter more for someone shipping today:

PinK is a new IDE. The Cocos Creator editor you know (and that I've shipped two projects on) is battle-tested. PinK is where visual editing is migrating — its maturity is unproven, and as of this writing it's shipping in alpha behind activation codes.
Migration has a cost. API cleanup and the deprecation cycle mean a 3.x project won't lift-and-shift for free.
The WeChat mini-game target is "gradual." For me this is the dealbreaker line — see below.

5. My call as a Cocos Creator 3.8 developer

My constraints are specific: my game is a WeChat mini-game, it's in production on 3.8, and all my hard-won optimization work — engine subpackaging, asset splitting, a runtime PerfTier — is built on 3.8 (I wrote it up in my bundle-size teardown). COCOS 4's WeChat support is still rolling out. Migrating now trades proven stability for an "open source" label I don't strictly need yet.

So my decision:

Stay on 3.8 for anything already shipping to WeChat — it's the stable, complete path today.
Evaluate COCOS 4 for a new project that needs native/Steam targets, a hard MIT requirement, and can tolerate an early PinK.
Watch, don't rush. The six-month deprecation window and the gradual mini-game rollout both reward patience.

The decision I run: platform target decides before version number does.

6. If you're still choosing an engine

None of this changes the core advice in my Cocos vs Unity vs Godot breakdown: for a WeChat or HTML5 mini-game, the 3.x line's native build pipeline and tiny first-load package are still unmatched. COCOS 4 makes the long-term future of that engine more open and more interesting — it just isn't the tool you need to switch to this afternoon. Decide by your distribution channel first; version number second.

7. Related reads

Originally published on Indie Game Lab. If you found this useful, that's where the deeper teardowns (bundle size, the full game post-mortem) live.

Cocos Creator 3.8 for Beginners: Build Your First Mini-Game

PHT — Fri, 09 Oct 2026 09:37:23 +0000

description: "A hands-on walkthrough to your first Cocos Creator 3.8 WeChat mini-game — project setup, the node + component model, your first TypeScript script, and the build-to-DevTools flow, with the gotchas I hit shipping a real game."

Cross-post note: This is the original article from my blog, Indie Game Lab. Read it there for the properly styled version, or keep reading here — it's identical.

TL;DR: You don't need a game-design degree to ship something on Cocos Creator 3.8 — you need the flow: create a WeChat mini-game project, understand that everything is a node with components, write one tiny TypeScript script, then build and preview in WeChat DevTools. I shipped a full survival/crafting game on this exact pipeline (the post-mortem is here), and the beginner path below is the same five steps I wish someone had handed me on day one — plus the three gotchas that cost me real hours.

This guide assumes zero Cocos experience. If you're still deciding whether Cocos is even the right engine, my engine comparison makes the call for a solo indie. If you've already built a prototype, skip to the build-and-preview section — but read the gotchas even if you skip everything else.

1. What you'll have at the end

By the end of this walkthrough you'll have a mini-game you can tap to play in WeChat DevTools: a character sprite that moves when you press a key or tap the screen, sitting in a scene you assembled yourself. It won't be the next hit — but it will be real, running code, and every game I've shipped started as exactly this: one sprite that does one thing.

More importantly, you'll internalize the one mental model Cocos is built around, because almost every beginner confusion (why doesn't my image show up? why won't it move? where do I put my code?) comes from not seeing it yet.

2. Step 1 — Create the project (and pick the right template)

Open Cocos Creator 3.8 LTS and hit New Project. Two choices matter:

Template: pick the 2D template (or the "Empty" 2D one if you want zero boilerplate). Most mini-games — including mine — are 2D.
Save path: avoid deep paths with spaces or Chinese characters. A short ASCII path like D:/dev/my-first-game saves you from cryptic build errors later.

You do not need to pick "WeChat Mini Game" as a template — that's not a starting template, it's a build target you choose later. Start in the editor like any other project; the WeChat part is a one-click build at the end.

3. Step 2 — The node + component model (the thing to understand)

This is the core. In Cocos, the scene is a tree of nodes. A node is just a position in space with a transform. It does nothing by itself. To make a node do something — show an image, play sound, run logic — you attach components to it. A sprite on screen is a node that happens to carry a Sprite component (which points at a texture) and a Transform component (where it sits).

This separation is why beginners get stuck: they add an image but forget the Sprite component, or write code but never attach the script component to a node. The rule is simple — code lives in components, components live on nodes, nodes live in the scene tree. Nothing runs unless it's attached to a node in the tree.

The whole engine in one picture: a node in the tree, the components that give it behavior, and the update loop that runs your script ~60 times a second.

4. Step 3 — Your first script (make it move)

Right-click the assets panel → New → TypeScript → name it MoveScript. Double-click to open it. Cocos gives you a stub with start() and update(). Edit it to:

import { _decorator, Component, Node } from 'cc';
const { ccclass, property } = _decorator;

@ccclass('MoveScript')
export class MoveScript extends Component {
  update(deltaTime: number) {
    // move right at 100 units per second
    this.node.setPosition(
      this.node.position.x + 100 * deltaTime,
      this.node.position.y,
      0
    );
  }
}

Now the crucial step beginners miss: attach the script to the node. Drag MoveScript.ts from the assets panel onto your Player node in the Hierarchy, or select the node and click Add Component → Custom → MoveScript in the Inspector. Hit the play button at the top — the sprite drifts right. That's your first game logic.

5. Step 4 — Build for WeChat Mini Game

Top menu → Project → Build…. Set:

Platform: WeChat Mini Game
Start Scene: your main scene
Appid: your WeChat mini-game appid (or use the "test" appid while learning — Cocos accepts a placeholder for local preview)

Two flags matter for real projects and trip up everyone eventually:

Separate Engine: ON. It splits the engine from your code so the engine is cached by WeChat and your updates stay tiny. I left this off once and wondered why every upload was huge.
MD5 Cache: ON for production. It lets WeChat cache unchanged files so players re-download less on update.

Click Build. Cocos outputs a folder (default build/wechatgame/). You don't open that folder directly — you open it with DevTools, next step.

6. Step 5 — Preview in WeChat DevTools (the gotcha)

Install WeChat DevTools (the mini-program IDE, not the consumer WeChat app). In Cocos Preferences → Engine Manager, point "WeChat DevTools Path" at the installed executable — Cocos uses it to auto-launch the preview.

The gotcha: never open WeChat DevTools first and then build. Build from Cocos first, then let Cocos (or the "Preview" button) launch DevTools and import the folder. If DevTools is already open on a stale build, it silently shows the old version and you'll think your code didn't take. Close DevTools, build, then preview.

Five steps, in order. The only non-obvious part is step 5: build before you open DevTools, or you'll be debugging yesterday's code.

7. Three gotchas that cost me real hours

The WeChat size ceiling is real. A mini-game's main package is capped at 4 MB, with subpackages adding more. My first build blew past it in a weekend. The fix isn't "make fewer features" — it's engine subpackaging, an asset audit, and a device-tier split, which I wrote up in my bundle-size teardown. Learn the ceiling now, not at launch.
Perf is a device problem, not an editor problem. It runs smooth on your laptop and stutters on a three-year-old phone. Draw calls and overdraw dominate the frame on mobile — my runtime perf teardown shows the three moves that fixed mine. Profile on a real device early.
Code that isn't attached to a node doesn't exist. If your script "does nothing," 9 times out of 10 it's not on a node in the scene tree, or the node isn't in the active scene. Check the Hierarchy, not the code, first.

8. Where to go next

You now have a sprite that moves. That's the seed of everything. From here the natural path is: add input (tap/keyboard) to control direction, add a second node as an obstacle, then a score. When you're ready to ship something bigger than a demo, the two articles that saved my real release are the bundle-size teardown and the draw-call optimization piece — read them before your build crosses a few megabytes or your frame time crosses 16 ms.

9. Takeaways

Cocos Creator 3.8 is approachable: create a 2D project, internalize that nodes carry components and components carry your code, write one update() loop, then build to WeChat and preview through DevTools (build first, open DevTools second). The engine hides the hard parts — package ceilings and mobile perf — until launch day, so learn those constraints early via the bundle and draw-call write-ups. Everything you ship later is just more nodes, more components, and more loops. Start small, ship the sprite that moves, then grow it.

Originally published on Indie Game Lab. If you found this useful, that's where the deeper teardowns (bundle size, draw calls, the full game post-mortem) live.