DEV Community: fuR Gaming

Adopt the Brain, Defer the Bridge: Unity’s Agent Plugin and Free CLI, Three Weeks On

Richard Fu — Sat, 19 Sep 2026 08:23:57 +0000

Unity shipped an official Unity agent plugin — 31 skills for Claude Code and Codex — and a free Unity CLI, three weeks after I published a decision log that deliberately ended in triggers instead of a calendar reminder: when X breaks, do Y. Every trigger fired, one conclusion broke outright, and the option I closed that post by saying nobody was selling turned up as a first-party product. This is what the frame got right, what it got wrong, and why “adopt the brain, defer the bridge” turns out to be the reusable part.

Beat: a decision log is worth more than a recommendation precisely because it can be graded later. This post is the grading.

1. What Unity shipped, in the frame’s own terms

Recap brain/bridge/generator in two sentences, link back to the original post, then sort the news into the three buckets — the sorting is the argument:

Layer	What Unity shipped	Verdict
Brain	31 skills written by the teams that own URP, UI Toolkit, WebGL, IAP	Free, additive, adopt now
Bridge	Unity CLI + experimental `com.unity.pipeline`, free, no AI seat	Defer — evaluate as fallback
Generator	nothing	Unchanged

Point: the frame’s value was never the taxonomy, it was that the three layers have independent adoption decisions. One launch, three different answers. A single verdict on “the Unity plugin” would have been wrong whichever way it went.

What this dates in the last post

Fold the corrections in here rather than back-editing the original, and say why in one line: that post is a dated decision log, and a log that edits its own history is worth less than one that gets graded in public.

Two things in it are now out of date, and both are worth stating in the open:

The entitlement claim was wrong within three weeks. I wrote that on a Personal seat the first-party bridge is not a free fallback. The Unity CLI and com.unity.pipeline are free, need no Unity AI entitlement, and run on Unity 6.0 LTS and newer. Worth noting the direction of my error: I understated a free option, so the cost of having read me is skipping something free rather than paying for something you didn’t need. I’d have corrected it in place if it ran the other way.

“Three different things are called Unity MCP” is now four. The CLI hosts a second first-party MCP — by most accounts free — alongside the entitlement-gated one in Unity AI Assistant. Sources still disagree on where that line falls. I wrote the section to complain the name was ambiguous; the ambiguity has since gotten measurably worse, which I’m taking as vindication rather than as a reason to stop naming things carefully.

Beat: this is the cheap half of being wrong in public. A dated log absorbs a drifted price without collapsing. A confident recommendation doesn’t.

2. The Unity agent plugin ships zero MCP servers, because Unity went CLI-first

The hard, checkable finding, and the post’s spine. Unity’s launch post describes the plugin as bundling “skills, the Unity CLI, and Unity’s MCP server for live Editor control.” Installed, claude plugin details unity reports:


Skills (31) ...
MCP servers (0)

Resist the urge to call this marketing dishonesty — the more interesting reading is architectural. unity mcp lives inside the unity binary. It is a subcommand, not a separate product: start it and it exposes a connected Editor’s commands as MCP tools over stdio, and unity mcp configure writes itself into sixteen AI clients. So the MCP server Unity mentions does exist. It just isn’t a thing the plugin installs, because the plugin installs no software at all.

What you actually get is documentation. The unity-cli skill tells the agent how to drive the Editor; the CLI, the com.unity.pipeline package and unity mcp configure are three steps you take yourself, deliberately, afterwards.

That gap — between “installs live Editor control” and “documents how you’d set it up” — is the entire reason adopt-the-brain-defer-the-bridge is available as a strategy. The knowledge layer and the control layer shipped in the same box and are not welded together. Had the plugin configured a bridge on install, adopting 31 skills would have meant swapping bridges underneath a working project, and I would have declined the whole thing.

Beat: the thing worth checking was never the launch post, it was the inventory. And the thing worth noticing is that Unity built CLI-first and made MCP a mode of it — which tells you which one they expect to last.

3. CLI or MCP? The token cost decides it, not the capability

The question I kept expecting to be hard, and isn’t — because for Unity they are the same capability wearing two coats. Same binary, same commands, same Pipeline package underneath. Nothing is reachable through unity mcp that isn’t reachable through unity command. So this was never a power comparison; it is an ergonomics and context-economics one, and almost nobody frames it that way.

What the CLI route costs and gives. The unity-cli skill sits at roughly 240 tokens always-on and only unpacks its ~13k when it actually fires. It runs in CI, in cron, in a plain shell, under any agent, or under my own hands. unity command invocations go into scripts and get version-controlled; MCP calls don’t. And discovery is dynamic — the CLI lists whatever the connected Editor currently exposes, so a new command shows up without re-registering anything.

What MCP adds, honestly. Typed tools the model sees without reading a skill first, which means fewer malformed invocations. Richer returns than stdout text — screenshots being the fair example, since an image coming back from a tool is natural over MCP and clumsy over a pipe. Per-tool permissioning in the harness.

What decides it. An MCP server’s tool schemas sit in the context window permanently, once per tool, whether or not you use them that session. A CLI’s cost is one skill description until the moment you need it. When your bridge exposes a couple of dozen tools this is a rounding error. When it exposes a hundred and eighty, it is the single largest fixed cost in your setup, and you are paying it on every trivial question you ask about the project.

Beat, and it generalises past Unity: we are used to comparing tools on what they can do, and these do the same things. The real question is what they cost you before you’ve done anything at all. Context is a budget now. Tool surfaces are rent.

4. The honest price of a free brain: what the Unity agent plugin costs in context

Balance section — resist the free-is-free reflex.

~5,943 tokens always-on, every session, every repo.
Of 31 skills, roughly 8 apply to my project. No IAP or LevelPlay (the web layer owns monetization), no tilemaps or sprite atlases (it’s 3D), no multiplayer (Photon is gone), no Unity-side localization — by design, since my Unity build renders no words at all.
Enable/disable is plugin-level only. You cannot trim per-skill, so the 6k is take-it-or-leave-it.

Beat: “free” tooling bills you in context window. That is a real currency now, and nobody prices it on the box.

5. The trap that came with the brain

The unity-cli skill instructs: “when an Editor is available, drive it instead of hand-editing scene or asset files” — and documents unity pipeline install, which would add a package to my manifest.

So adopting the brain quietly imported an advocate for the bridge I had just decided to defer. Not malice, not even a flaw — the skill is correct in general and wrong for my specific standing decision. But a future session acting on that instruction would silently reverse a deliberate choice.

Beat, and the transferable one: skills carry opinions, and an opinion you did not choose is a decision made on your behalf. The mitigation is boring — write the standing decision down where the agent reads it, not just in your own head. Generalizes to any team adopting any vendor’s skill pack.

6. The option nobody sells you got sold

The punchline. I closed the last post recommending a batch-mode CLI entry point specifically because no vendor was attached to it — arguing that the durable choice was the one that survived every acquisition scenario. Two weeks later Unity shipped precisely that: free, first-party, live-Editor control, [CliCommand] custom tools, no AI entitlement.

Two honest readings, give both:

Flattering: if your reasoning lands on a capability the platform vendor ships weeks later, the reasoning was tracking something real.
Deflating: I recommended it because it was unowned, and it is now owned. The property I valued is the one that went away. A first-party CLI can be deprecated, entitlement-gated later, or folded into a paid tier — the vendor-free road now has a vendor on it.

I still think adopting it is right, and I notice the argument that got me there no longer applies. Say so plainly rather than claiming the prediction.

Also: it is not polished. Bearer tokens regenerate on domain reload and strand clients on 401s. The Editor still wants foreground focus before refreshing assets — the single quirk that has cost me the most time. ~0.80s per call. First-party means someone is on the hook, not that the edges are gone.

7. The conclusion that broke: modality, not capability

The honest failure. I wrote that generated meshes actively fight assets with radial mechanical symmetry, sharp edges, separable parts, and a pivot that must sit exactly on an axis — using my own spinning tops as the example.

That was an argument against diffusion text-to-mesh , and I wrote it as though it were an argument against generated 3D. GPT-6 Astra (3 September 2026) is a different modality: an agent operating Blender, writing real Python, rendering, revising. It can name object hierarchies, set an origin exactly on an axis, assign per-part materials, export FBX. Every specific objection I raised is an objection to the technique I happened to have in mind.

State the uncertainty properly:

I have not tested it on my own tops. Capability correction, not a result.
Published weaknesses are organic shapes and topology-heavy work; strengths are hard-surface, naming, materials, export. My case sits in the strong half, which is suggestive, not evidence.
Access is the real blocker for a solo dev: on ChatGPT Plus, Astra is metered inside Work and Codex at 5–45 local messages per 5 hours. A multi-part hard-surface model with revision loops eats that. I deferred on cost, and I should be clear that I deferred on cost and not on capability, because those are different admissions.
BenchCAD: 95.9% voxel IoU, against 84.3% for the model I actually use daily. Report it; don’t bury it.

Beat: the correction worth publishing isn’t “I was wrong about a product,” it’s “my rule was missing a qualifier I didn’t know it needed.” Rules that name a technique age; rules that name a capability don’t.

8. What I actually did

Short and concrete, so the post lands as a log and not an essay:

Installed the skills plugin, user scope, all six repos. Free, additive, reversible.
Left the bridge alone. No package added to any manifest.
Promoted the Unity CLI to pre-chosen fallback, displacing the MIT community bridge in my trigger list.
Recruited Codex as a generator, not a replacement brain — image generation routed into my existing agent on subscription billing rather than API metering, because asset generation is out-of-band by nature and the filesystem was always the integration point.
Declined Blender MCP on metered cost. Trigger: when a shipping asset actually needs it.
Wrote the deferred-bridge decision down where the agent reads it.

9. The reusable heuristic

When a platform vendor ships an AI tooling bundle, unbundle it before deciding, and give each layer its own answer:

Knowledge is nearly free to adopt — additive, reversible, priced in context rather than money.
Control is expensive to switch — the cost is never the tool, it’s the accumulated knowledge of one tool’s quirks, and you pay it again on every swap.
Generation should be bought from whoever generates — bundled generators are resellers, and the modality moves faster than any bundle tracks.

Adopt the brain. Defer the bridge. Buy the generator direct.

Close on the thing that made the exercise worth it: the grading only worked because the original post committed to triggers rather than a verdict. A post that had said “here is what I recommend” would have been silently wrong for three weeks. One that said “here is when I will change my mind” got to be checked. That is the argument for writing decision logs, and it has nothing to do with Unity.

References to collect before writing

Unity — official plugin for Claude Code
Unity — official plugin for Codex
Unity — Meet the Unity CLI
Unity Docs — plugin for third-party agents (Claude Code, Codex, Grok)
Unity Docs — Pipeline package
GitHub — Unity-Technologies/unity-agent-plugin
Vindler — the Unity CLI: what ships, what is broken
OpenAI — GPT-6 Astra
Astra-in-Blender write-ups + BenchCAD numbers
Astra access/limits by plan (Plus = Work/Codex only, metered)
My own: Brain, Bridge, Generator: Comparing Unity MCP Options After the Coplay–Aura Acquisition

Written September 2026. Same caveat as last time, and it earned its keep faster than I expected: prices, tiers and licence terms will drift, this is a decision log rather than a benchmark, and the Astra section is a corrected capability claim I have not personally tested.

The post Adopt the Brain, Defer the Bridge: Unity’s Agent Plugin and Free CLI, Three Weeks On appeared first on Richard Fu.

Brain, Bridge, Generator: Comparing Unity MCP Options After the Coplay–Aura Acquisition

Richard Fu — Thu, 20 Aug 2026 14:09:25 +0000

My Unity AI setup cost $0 for months, and then the company behind half of it got acquired. That sent me through the Unity MCP alternatives I’d never seriously looked at — and the answer turned out to be less about picking a replacement than about noticing I’d been comparing the wrong three things.

The setup that was working fine

I build a small Unity game on my own. My editor-AI setup arrived by accident rather than design: I started on the free MIT-licensed CoplayDev/unity-mcp bridge, liked it, and after a while moved across to Coplay’s own MCP — the proprietary product from the same shop. That ran for months. It worked genuinely well, and it cost me nothing.

My mental model of what I used it for was simple, and — I’d find out later — wrong. I thought of it as the thing that generated sound effects, plus the occasional texture. Nice to have. Replaceable.

Then I read that Coplay had been acquired, and the two obvious questions arrived together. Is this getting sunset? And is there any actual benefit to moving to the acquirer’s product?

What actually happened

Ramen, the studio behind Aura — an AI assistant for Unreal Engine — acquired Coplay in March 2026, making Aura the first assistant covering both engines. Aura for Unity launched on 14 May 2026. Coplay itself has no announced sunset date and, per the announcement, continues “as a legacy product.”

If you’re happy where you are, nothing needs to change. Unity MCP will also remain free, open source, and MIT-licensed.

— Coplay, What’s next for Coplay

Which is reassuring right up until you notice that the sentence contains a landmine of ambiguity. “Unity MCP” means at least three different things in this ecosystem, and the promise applies to exactly one of them.

Three different things are called Unity MCP

Untangling this was the single most useful ten minutes of the whole exercise, because the free-forever guarantee attaches to the project I’d left, not the one I was using.

Thing	Cost	Asset generation	Fate
CoplayDev/unity-mcp (MIT)	None, ever	None — editor control only	Explicitly guaranteed free and open source; Aura now sponsors it
Coplay MCP (account)	Free tier via a Coplay account	Yes — sfx, music, images, 3D models	Legacy. Running, undeveloped, no end date
Unity’s own MCP (metered)	Bundled on Pro; needs a paid Unity AI seat on Personal	Textures, materials, skyboxes, 3D — no audio	First-party, actively developed

So “the MCP stays free” and “my setup stays free” were two different claims, and I’d been treating them as one.

The reframe: three markets, not one

Every comparison I read mushes these together, which is why the choice looks harder than it is. There are three separable products here, and most people already own one of them outright.

Brain — the agent that reasons and writes the code. If you drive Unity from a coding agent in your terminal or IDE, you already have this and it is the best part of your stack. Nothing below competes with it.

Bridge — the MCP server giving that brain hands inside the editor: read the hierarchy, check compile errors, tail the console, enter play mode, screenshot a scene. This is the part that quietly becomes load-bearing.

Generator — text-to-texture, text-to-mesh, text-to-sound. A completely separate market with its own vendors, and the one where in-editor assistants are acting as resellers.

Once split this way, the acquisition question shrinks. I don’t need a new brain. I don’t need a bundled generator. I need to know that a bridge will exist, and the Unity MCP alternatives turn out to be abundant and free.

Comparing the Unity MCP alternatives

This is a crowded, healthy field — not a three-way vendor choice. Four credible free Unity MCP alternatives, plus the first-party one.

Project	Licence	Tools	What distinguishes it
CoplayDev/unity-mcp	MIT	~47	The default. Largest community by a wide margin, active releases through 2026, sponsored by Aura post-acquisition
IvanMurzak/Unity-MCP	Open	70+	Custom tools via C# attributes. Also runs inside a compiled build, not just the editor
CoderGamester/mcp-unity	Open	—	Mature and broadly client-compatible across the major agents and IDEs
FoxsterDev/xuunity-mcp	MIT	—	Validation-first. Compile checks, test runs, scene assertions, deliberately small mutation surface, no external runtime
Unity official	Seat	—	First-party and durable, but gated behind a Unity AI entitlement unless you’re on Pro or above

Two of these are interesting for non-obvious reasons

Tool counts are the least useful column in that table. The two entries worth actually thinking about earn it on posture, not breadth.

Validation-first is aimed at the failure mode you actually hit. I keep a running file of bridge quirks I’ve been bitten by, and reading it back was instructive: a save-scene tool that silently performed save-as, a script-execution tool that no-ops after a domain reload, a compile check that cheerfully reports a stale build as clean. Almost every entry is a mutation tool lying to me. A bridge whose entire thesis is “small mutation surface, trustworthy compile and test and assert” is pointed directly at that, and nobody markets it that way because “fewer tools” is a terrible tagline.

Custom tools beat vendor tools, and only one option offers them. My real verification loop isn’t generic Unity work — it’s “run the batch harness across a range of inputs”, “replay a recorded line and diff the output against what it produced last time”, “assert the state machine actually reached its terminal state.” I currently reach all of that through fragile generic script-execution calls. Three or four purpose-built tools exposing my own harness would beat any vendor’s eighty-something generic ones, because they’d speak my domain instead of Unity’s. That capability is worth more than every paid feature I looked at, and it’s free.

The paid tier, honestly assessed

I did the work of pricing both, so here it is.

Unity AI gives Personal-plan users a 14-day trial with 1,000 credits, then $10/month for 1,000 credits. Pro, Enterprise and Industry seats include credits and MCP access by default. That last detail matters more than the price: on a Personal seat, the first-party bridge is not a free fallback. There’s an active community thread asking Unity to change this, and another asking for clarity on the policy at all, which tells you how settled it currently feels.

Aura runs a two-week trial with $40 of credit, then Indie, Pro and Ultimate tiers. Its pricing docs contain the detail that decided it for me: when you use its MCP tools from an external IDE, basic inspection is billed to your IDE subscription, but triggering its specialised subagents consumes Aura credits. That’s a fair model — and it means I’d be paying per-invocation for the loop I currently get free, in exchange for an in-editor agent I don’t need, because I already have a brain.

The reseller tell. Coplay’s own comparison page lists 3D model generation “using your provider of choice (e.g. Meshy)” as a premium feature. That’s honest, and it’s also the whole story: the in-editor assistant is a convenience wrapper over generators you can subscribe to directly.

So buy generators from generator companies

If you want generated meshes, the direct vendors are cheaper and better at it than any wrapper: Tripo from around $14–20/month, Meshy at $20, Hyper3D/Rodin with a free generation tier and the strongest reported quality for hero assets. Side-by-side credit pricing is worth a look before committing to any of them.

Two things I’d flag that the marketing doesn’t.

First, generated meshes suit some assets and actively fight others. Anything with radial mechanical symmetry, sharp edges, parts that must stay separable, a pivot that has to sit exactly on an axis, and colliders keyed to geometry — you’ll pay for the generation and then spend the same hours you saved splitting a fused blob apart in Blender. Environment dressing, props, background silhouettes, skyboxes and textures are where this technology currently earns its keep.

Second, audio is the real gap. Unity AI’s generators cover textures, materials, skyboxes and 3D. There is no audio generator at all. If in-editor sfx generation is what you value, no first-party or free-bridge option replaces it, and you’re going direct to an audio vendor whether you like it or not.

On which — a licensing trap worth knowing, since it’s the one place my own “it’s free, it’s fine” reasoning was genuinely broken. ElevenLabs’ free tier is generous on capability: 10,000 credits a month, sound effects included, plenty for a small project. But it grants no commercial licence — free-tier output can’t be used commercially, and non-commercial publishing wants attribution in the title. Starter at $6/month is the cheapest tier that includes commercial rights, and rights persist for whatever you generated while paying. So the correct move isn’t a standing subscription: it’s one paid month covering the session that produces your shipping audio, then back down to free for experimentation. The trigger is “this ships”, not “the credits ran out.”

The option nobody sells you

Worth naming, because it never appears in these comparisons and it may be the most durable choice available: drop the bridge for anything that doesn’t need a live editor.

A Unity batch-mode entry point — -batchmode -executeMethod pointed at your own harness — makes your verification runnable from a plain shell. No MCP server, no vendor, no port collision when you’ve got two editors open, no dependency on anybody’s acquisition. It survives every scenario in this post. The live bridge then stays for the things that genuinely need eyes: screenshots, poking around in play mode, inspecting a hierarchy you can’t picture.

I’d been treating the bridge as the only road into my project from a terminal. It isn’t, and the CLI road doesn’t have a vendor attached.

What I decided

Nothing, immediately — which is a real decision rather than an absence of one. Coplay is up, there’s no sunset date, and I’m a light user of the part that’s actually at risk. Migrating on speculation costs me the accumulated knowledge of one tool’s quirks in exchange for learning another’s.

What changed is that I now hold triggers instead of a diary date.

When the editor plugin breaks on a Unity upgrade → move to one of the free MIT-licensed Unity MCP alternatives. Chosen in advance, no research under pressure.
When generated audio stops being placeholder and ships → one paid month at an audio vendor for the commercial licence, then downgrade.
When props and environment need real volume → subscribe to a 3D generator directly, never through a wrapper.
When I want to spend an hour improving tooling → custom domain tools and a batch-mode entry point, not a bridge swap.

That last one is the actual conclusion. Every one of the Unity MCP alternatives in this post, at best, restores what I already have for free. The only work that makes my setup better is the work no vendor is selling: tools that speak my project’s own vocabulary, and a path into the project that doesn’t route through anybody’s product.

The part that was worth the scare

Legacy products rarely die by announcement. The realistic failure modes are quieter than a sunset notice: an engine upgrade breaks a plugin nobody is patching any more, or an upstream API key silently expires and a generation tool starts returning errors. Waiting for a formal end-of-life date means being surprised by neither of those.

But the acquisition was worth more to me as a forcing function than as a decision. Asked cold what I used the tool for, I said sound effects and the odd texture. Then I actually looked — and the load-bearing dependency was the compile-check, console-tail, play-mode, screenshot loop that I lean on constantly and had stopped noticing precisely because it works. The convenience I’d have named first was almost the only part I could lose without flinching.

That’s the transferable bit, and it has nothing to do with Unity. When a tool in your stack changes hands, the useful response isn’t picking a replacement. It’s inventorying what’s actually load-bearing — because there’s a good chance, as there was for me, that you’d have named the wrong thing.

References

Prices, tiers and licence terms checked August 2026 and certain to drift. This is a decision log, not a benchmark — I compared these on documentation and posture, not by running each bridge through the same project, and I haven’t migrated off anything yet. Corrections welcome.

The post Brain, Bridge, Generator: Comparing Unity MCP Options After the Coplay–Aura Acquisition appeared first on Richard Fu.

Particle Trail Stuck at X=0: A Unity Update-Order Bug (and Six Wrong Fixes)

Richard Fu — Tue, 30 Jun 2026 15:25:04 +0000

I wanted a simple thing: a little particle trail that streams behind a fast-moving character as it runs down a lane and slides left/right. A few hours and six failed fixes later, I finally understood why the particles kept piling up in the dead center of the lane while the character was clearly off to one side.

The bug had one strange, very specific signature that I ignored for far too long:

The trail followed the character in Y and Z , but its X was always pinned to 0.

That asymmetry was the whole answer. It took me most of the session to listen to it. This is the honest version — wrong turns first, then the root cause, then the fix and the lessons.

The setup

A Unity 6 / URP game. A character runs forward automatically and is nudged left/right between lanes. I attach a looping CPU particle trail (a standard Shuriken system from an art pack) to the character so it leaves a fun streak.

In the editor, if I grab the character and drag it around by hand, the trail follows perfectly. In play mode, the streak renders in the center of the lane no matter where the character actually is. New particles don’t appear at the character — they appear at world X ≈ 0.

Wrong turn #1 — “the spawn position is wrong”

My first instinct: I’m instantiating the trail at the wrong place, or not parenting it. I “fixed” the parenting and zeroed the local position. No change.

Wrong turn #2 — “stop re-instantiating; cache and reuse”

I rewrote it to pre-instantiate one trail per type and just activate/deactivate them, reasoning that per-event Instantiate was somehow mis-placing things. Cleaner code. Same bug.

Wrong turn #3 — “it’s World-space particle semantics + speed”

I reasoned that with World simulation space , particles are stamped into the world where they’re born and left behind, and with a long lifetime over a fast run they’d stretch back toward the start (≈ X=0). So I shortened particle lifetime to make a tight “comet tail.” Same bug — still centered.

Wrong turn #4 — “use Local space, it’ll stick to the character”

I forced Local simulation space. Now the particles did stick to the character… but they clustered on it with no trailing streak at all. I’d traded one wrong behavior for another, and — critically — I never confirmed Local had actually taken effect (more on that below).

Wrong turn #5 — “add a world-space backward velocity to fake the streak”

Local emission + a world-space backward velocity to make particles hang behind. This threw Particle Velocity curves must all be in the same mode (you must set X/Y/Z velocity curves together), and when fixed, re-introduced the X=0 behavior. I’d reintroduced a world-space transform path and the bug came back with it.

At this point I had changed six things and understood nothing. That’s the signal to stop guessing and start measuring.

The measurements that cracked it

Two probes finally produced facts instead of theories.

Probe 1 — the emitter vs. the particles. I logged, every frame, the emitter’s world position and the particle system’s render-bounds center (where the particles actually are in the world):


emitter world = (1.04, 0.69, 30.28)
particle bounds center = (-0.04, 0.69, 30.24)

The emitter was genuinely at X=1.04. The particles were at X≈0. Y and Z matched the emitter; only X was wrong. So this was never a parenting bug — the GameObject was on the character. The particles were being born at the wrong X.

Probe 2 — what simulation space is actually running. The same log printed:


sim = World

…even though my code now set the field default to Local. That’s a Unity trap I’d walked straight into:

Changing a field’s default in code does not change the value already serialized on a component. The component had been saved with simulationSpace = World earlier, so every “Local” change in code was silently ignored.

So my “Wrong turn #4” had never even run as Local. Once I set the serialized value to Local, the particles finally tracked the character’s X — confirming the bug was specific to World-space emission.

The root cause: particle trail emission timing

Now the axis asymmetry made total sense. The character’s motion was split across two scripts on two different update steps :

Forward (Z) was applied in Update.
Lateral (X) was applied as an override in LateUpdate — a second controller wrote transform.position.x = laneX late in the frame.

For most of the frame, the character’s X sat at ~0 (the forward controller pulls it toward a neutral target); only LateUpdate slammed it back to the real lane value. A World-space particle system samples the emitter’s position when it emits — before that LateUpdate correction lands — so every particle was stamped at X≈0. Z was never overridden late, so Z was always correct. Hence: follows Y and Z, stuck at X=0.

It was never the prefab, the parenting, the scale, the lifetime, or the simulation space by itself. It was frame update order colliding with how/when particle systems read the emitter transform. Any World-space particle trail attached to this character would break identically — so “try a different particle pack” would have wasted even more time.

The fix: a Local-space particle trail

I stopped trying to make World-space emission work and rebuilt the particle trail on Local space, which is immune to the timing problem because it emits relative to the emitter no matter when the transform settles:

Local simulation space — emission is always at the character (correct X). Confirmed by render-bounds tracking the emitter.
A local −Z backward drift ≈ the run speed — so particles, born at the character, drift backward in the character’s frame at roughly the speed the character moves forward. Net world motion ≈ zero, so they hang on the ground and fade — a real leave-behind trail, but produced by velocity rather than by world-space emission.
Disable the prefab’s Limit-Velocity (clamp) module — it was capping speed to ~1 and damping the backward drift to nothing (particles clustered). This was the difference between “blob on the character” and “streak.”
Lower the particles’ Start Speed — the prefab fired them outward at random; with the clamp off, that randomness sprayed everywhere. A low start speed lets the drift line them up.
Spawn-per-event, self-despawning — each pickup spawns its own short-lived instance that stops emitting after its duration and destroys itself once the tail fades; long-lived trails are stopped on a game event. Simple, no pooling.

Everything became an inspector knob (drift speed, lifetime, start speed, emit height per trail type), because the “right” values are pure visual taste.

Pitfalls, collected

Listen to axis asymmetry. “Y and Z are fine, X is wrong” is not a particle problem — it’s a which-thing-touches-X-differently problem. That should have pointed me at the lateral controller and update order in minute five.
Measure the particles, not the emitter. I kept confirming the emitter followed the character (it did) and concluding “so it should work.” The particles’ render-bounds center was the only thing that mattered, and I logged it last instead of first.
Don’t trust idle samples. An early probe showed the character at (0,0,0) and I briefly concluded “the world scrolls, the character is stationary.” It was just sampling before the run started. One bad sample sent me down a whole wrong model.
Serialized values silently override code defaults. Changing a public field’s initializer doesn’t touch components already saved in a scene/prefab. If a code change “does nothing,” verify the actual runtime value, not the source default.
Particle velocity curves are all-or-nothing per mode. Set X/Y/Z together or Unity throws.
A “Limit Velocity over Lifetime” module will quietly eat any velocity you add. If your forces seem to do nothing, check the clamp.
Six fixes without a measurement is a process failure, not bad luck. The rule should kick in much earlier: after the second failed fix, stop and instrument.

Self-reflection

The technical lesson is real (update order vs. particle emission timing, and Local-space + drift as a robust workaround). But the meta-lesson is the one that actually cost the hours: I pattern-matched to plausible causes — parenting, instantiation, world-space semantics — and “fixed” each before I had any evidence it was the cause. Every one of those fixes was a guess wearing a confidence costume.

The turning point wasn’t cleverness; it was switching from explaining to measuring — logging the emitter against the real particle positions, and printing the runtime simulation space instead of assuming my code default applied. Both took five minutes and immediately ended the guessing. The clue I needed (Y/Z follow, X doesn’t) was in the very first bug report. Next time: when a symptom is that specific, treat the specificity as the lead, and reach for the probe before the fix.

And there was a second clue I held the whole time and failed to read. Early on I’d parented the trail under the character and, in play mode, dragged the character around by editing its Transform position by hand — and the trail followed perfectly. I filed that under “so the parenting is fine” and moved on. But it was telling me something sharper: a manual Inspector edit sets the transform directly and statically — it is not re-applied every frame by a script, so it never participates in the Update→LateUpdate tug-of-war that the runtime controllers do. With the scripts off the hook, the emitter X just sat at the value I dragged it to, and World-space emission sampled it correctly. The only difference between “works” (manual drag) and “broken” (play mode) was whether scripted, frame-ordered position updates were involved at all. That contrast points almost directly at update timing — if I’d asked “what is different about how position gets set in the two cases?” instead of “is it parented?”, I’d have arrived at the LateUpdate override hours earlier. A test that works is not just reassurance; the reason it works is often the diagnosis.

The post Particle Trail Stuck at X=0: A Unity Update-Order Bug (and Six Wrong Fixes) appeared first on Richard Fu.

Unity WebGL Particles Invisible? Causes and How to Fix It

Richard Fu — Sun, 28 Jun 2026 15:39:18 +0000

I spent the better part of a day chasing a celebration firework that played perfectly in the Unity editor and rendered absolutely nothing in the WebGL build. No errors. The particles spawned, played, sat right in front of the camera — and stayed invisible.

I diagnosed it confidently four times. The first three were wrong. The only thing that ever found truth was a dumb A/B test in the actual build — not in the editor, not by reading shaders, not by theorizing. That turned out to be the real lesson, so I’ll tell it honestly — wrong turns and all — and then map out what WebGL genuinely can and can’t do with particles.

The setup

A Unity 6 / URP mobile-style game shipped to WebGL. The win screen opens a treasure chest with a firework burst and a soft neon glow over the whole scene. Two things broke only in the WebGL build:

The bloom/glow was missing.
The firework was completely invisible — despite the particle system clearly running.

They turned out to be unrelated, which is part of why this took so long.

Wrong turn #1 — right, but only for the glow: shader variant stripping

URP strips “unused” shader variants from builds to save size, and the editor never strips. So editor-works / build-doesn’t should make you suspect stripping first.

The missing bloom was exactly that — URP’s Bloom post-processing variant was being stripped on WebGL (Strip Unused Post Processing Variants). Disabling it brought the glow back (I later moved the glow to MK Glow , a renderer feature — see the quality-tier trap below).

Good fix — for the glow. Then I made the classic mistake: I assumed the firework had the same villain.

Wrong turn #2 — “the Shader Graph must render black on GLES3”

The firework was from a popular Shader-Graph-based pack (Cartoon FX Remaster). I instrumented the celebration code:


firework diag @t=2.5s: totalParticles=164 anyPlaying=True anyVisible=True
shaders=[Cartoon FX/Remaster/Particle Procedural Glow, Particle Ubershader]

Particles exist , system playing , renderer on-screen , real shaders (not the magenta error shader). Yet no visible color — even when I cranked a glow pass to blow out the whole screen, the firework area simply never appeared.

My conclusion sounded airtight: Unity WebGL = WebGL 2.0 = OpenGL ES 3.0 , and Unity cross-compiles its HLSL down to GLSL ES 3.00. For a big particle “ubershader,” I figured the cross-compiler was emitting GLSL that compiles but outputs black — a translation bug that bites only on the GLES3 path, never in the editor (Metal/D3D).

Plausible. Confident. Wrong — as I’d find out two diagnoses later.

The fix that worked — for a different reason than I thought

I swapped the Shader-Graph firework for an Epic Toon FX firework — CPU ParticleSystem (Shuriken) + URP/Particles/Unlit. Plain, old, boring tech. It rendered in the editor immediately.

…and was invisible in the WebGL build. Again.

Wrong turn #3 → the first confirmed truth: Soft Particles need a depth texture

Same signature — plays in editor, audio + feedback fire (so it’s emitting), nothing on screen. But this time the cause was real and provable. I inspected the live materials:


shader: Universal Render Pipeline/Particles/Unlit
keywords: [..._SOFTPARTICLES_ON...] _SoftParticlesEnabled = 1
URP 'High' (WebGL tier): supportsCameraDepthTexture = False

Soft Particles — the fade where a particle meets opaque geometry — needs the camera depth texture , and the WebGL tier wasn’t generating one. With no depth bound, the fade reads an unbound texture: desktop returns “far” (visible); WebGL GLES3 returns 0 → alpha ≈ 0 → fully transparent. Same material, opposite result per platform. No shader error — it compiles fine and fades itself to nothing.

Confirmed via the WebGL console (Playwright): zero shader errors — a runtime fade, not a compile failure. The fix was one toggle: turn Soft Particles off (an open-air firework never intersects geometry, so they did nothing anyway). The firework finally rendered on WebGL. 🎆 It’s also why the coins were fine the whole time: opaque, no soft particles, no depth dependency.

So I’d “solved” it — and, generalizing, told myself the original CFXR firework must have been soft particles too. Tidy unified theory. Also wrong.

The reckoning: a 30-second A/B test demolishes my Shader-Graph theory

The chests also carried a CFXR glow halo (CFXR3 LightGlow A (Loop)). If “CFXR renders black on WebGL” were true, those would be invisible too. So I tested it the only way that matters — in the build : two chests at the start line, one with the CFXR glow, one without.

The one with the CFXR glow glowed. On WebGL. The pack I’d declared “renders black” was rendering just fine.

So I pulled the shader keywords of a CFXR material that works (the glow) and one that fails (the firework):


WORKS "cfxr stretch ray blur add" → _CFXR_ADDITIVE, _FADING_ON
FAILS "cfxr stretch trait blur add" → _CFXR_ADDITIVE, _FADING_ON ← identical

Identical shader, identical keywords, identical soft-particle settings — one renders, one doesn’t. That kills every shader-level theory at once: not the Shader Graph, not the variant, not soft particles, not HDR. The same compiled shader draws in the loop-glow and draws nothing in the firework burst.

The real differentiator is at the ParticleSystem / effect level — the failing effects are complex one-shot bursts (sub-emitters, velocity, lifetime curves, the pack’s lifecycle script); the working one is a simple loop glow. Something in the burst machinery doesn’t survive the WebGL runtime — particles spawn and the renderer reports on-screen, but they contribute no visible pixels. I never pinned the exact module, and didn’t need to: the game ships the working glow + the fixed CPU firework.

The honest scoreboard:

The glow was shader-variant stripping. ✅ correct
The CPU firework was Soft Particles + no depth. ✅ confirmed
“CFXR renders black on GLES3”? ❌ wrong. CFXR renders on WebGL; some of its burst effects don’t, for a non-shader reason I never proved.

Three confident diagnoses, one survivor. The thing that exposed each wrong one was the build , not the editor.

Which Unity WebGL particles actually render (a GPU-feature wall)

The useful map. WebGL 2.0 / GLES3 supports modern vertex/fragment shaders (GLSL ES 3.00) but has no compute, geometry, or tessellation shaders.

Tech	Runs on WebGL2?	Why
Built-in / URP standard shaders	✅ always	simple frag/vert, cross-compiles cleanly
CPU `ParticleSystem` (Shuriken)	✅	CPU sim + standard shaders
Shader Graph	✅ usually	generates a normal shader; mostly fine on GLES3
VFX Graph	❌ never	GPU-simulated via compute shaders — absent on WebGL2
Geometry / tessellation	❌ never	absent on WebGL2

I deliberately softened the Shader Graph row from my first draft — I’d written “can render black,” but my own A/B test later showed the Shader Graph renders fine and the failures were elsewhere. Shader Graph is an authoring tool that emits an ordinary shader: treat it as “usually fine, verify in build,” not “cursed.”

VFX Graph is the categorical wall: it simulates particles on the GPU via compute shaders, and WebGL2 has no compute, so it can’t run at all. That’s why “Realistic Fireworks — VFX Graph, supports URP!” asset-store packs are a non-starter for WebGL.

“Supports URP” describes the render pipeline, not the platform. Your constraint is WebGL, not URP.

A bonus trap: the editor lied via the quality tier

When I added MK Glow it rendered in the WebGL build but did nothing in the editor — sliders had no effect. I burned time on render-graph theories before introspecting the live editor:


QualityLevel 2 (PC) → PC_Renderer (no MK Glow)
QualityLevel 3 (High)→ Default_Forward_Renderer (has MK Glow) ← WebGL uses this

The editor was previewing on the PC tier — a different renderer than WebGL’s High tier — so my feature wasn’t even in the active pipeline. Setting the editor to High gave instant preview. Bonus gotchas from the same hole: the Scene view doesn’t render custom renderer-feature passes (only the Game view does), and Volume edits made during Play mode revert on Stop.

Unity ↔ three.js (because the compute wall is universal)

The same wall shows up in three.js — with a different escape hatch.

Concept	Unity	three.js
Shader authoring abstraction	Shader Graph	TSL (Three.js Shading Language)
Raw shader code	HLSL / ShaderLab	GLSL / WGSL
GPU compute	Compute Shaders (HLSL)	WebGPU compute / TSL compute fns
GPU particle sim (compute)	VFX Graph	GPU-compute particles (TSL + WebGPU)
CPU particle sim	Shuriken `ParticleSystem`	CPU-updated `Points`/sprites

Two things people (me included) get backwards:

TSL ≈ Shader Graph, not VFX Graph. It’s an authoring layer — you write shading logic in a JS node API and TSL compiles it to WGSL (WebGPU) or GLSL (WebGL2 fallback). It can also author compute, but that’s one capability, not its identity.
The equivalent of VFX Graph is GPU-compute particles built with TSL compute on the WebGPU renderer — the technique, not the language.

The strategic difference today: three.js is well ahead on WebGPU (its WebGPURenderer + TSL are production-usable, and WebGPU browser support is real and growing), so you can ship GPU-compute particles there if you target WebGPU. Unity’s web export is still WebGL2/GLES3 (its WebGPU backend is experimental), so for a shipping Unity web game you assume no compute → no VFX Graph , and CPU particles + standard shaders are the lane. The “realistic GPU fireworks” I wanted would be on the table in three.js-on-WebGPU; on Unity-on-WebGL2, the boring CPU ParticleSystem was the right — and only — answer.

Takeaways

Test in the actual build — every time. The editor renders through a different backend (Metal/D3D), often a different quality tier, and never strips shaders. Every wrong diagnosis came from trusting the editor or my own reasoning; every correction came from the build.
Invisible particles have several unrelated causes — shader-variant stripping, Soft Particles (no depth texture), and particle-system quirks all produce the same “spawns, on-screen, invisible.” Don’t pattern-match the second case to the first.
Soft Particles need the depth texture the WebGL tier doesn’t provide → silent fade to invisible. Turn them off, or enable Depth Texture (at the cost of a pass).
VFX Graph never ships to WebGL (needs compute). Shader Graph usually does — verify in build; don’t assume it’s “black on GLES3.”
“Supports URP” ≠ “supports WebGL.” Platform, not pipeline, is the constraint.
Know when to stop. I never fully pinned why the CFXR firework burst was invisible here (CFXR otherwise renders fine on WebGL — the chest glow proves it). Once a reliable alternative worked, the forensics weren’t worth it.
Stay humble about confident diagnoses. I had three airtight ones. A 30-second in-build A/B test beat all of them.

The firework glows now — a CPU particle system from decade-old tech, lit by a renderer-feature glow, rendering happily in a browser. Sometimes the boring tool is the right tool. And the fastest debugger is often two objects side by side in the actual build.

The post Unity WebGL Particles Invisible? Causes and How to Fix It appeared first on Richard Fu.

Building MESH: A Civic Resilience Platform With AI Agents

Richard Fu — Sat, 23 May 2026 08:27:29 +0000

A one-day hackathon project at the Claude Impact Lab (Melbourne, May 2026). The brief was open. I built MESH — Melbourne Exchange & Solidarity Hub — a gamified civic platform where residents see their suburb as a node in a network and AI agents read live open data to suggest the most useful thing the community can do next.

1. Why MESH

Every Australian suburb is sitting on quiet abundance. Gardens that produce too much. Retirees who could teach welding. Neighbours who’d happily check on each other in a heatwave if anyone asked. The capacity exists. The wiring doesn’t.

Three observations led me to MESH:

Civic capacity is fragmented. There’s no shared map of who can teach what, who has spare zucchini, who’s ready in a heatwave. The information lives in group chats, in heads, in council PDFs nobody reads.
Open data is inert. data.melbourne.vic.gov.au alone publishes 239 datasets. Almost none of them inform a decision a resident will make this week. The data isn’t missing — the loop is.
The unit of resilience is the suburb. “City-wide” is too coarse to coordinate. “Neighbourhood” is too granular to measure. The 3-km suburb — Carlton, Footscray, Brunswick — is the natural unit. So MESH scores, narrates, and gamifies at that scale.

The vision: each Melbourne suburb gets a resilience index (R-index) derived from five pillars — food security, skill density, resource sharing, social connectivity, emergency preparedness. AI agents read each suburb’s data and suggest the most impactful initiative residents could run this week. Completing it earns XP. The suburb’s score moves. The board updates. Other residents see it. It is meant to feel like a slow-motion multiplayer game.

2. What it does — a five-minute tour

The map

The home page is the centrepiece. A real Google Maps WebGL view of inner Melbourne with five suburb polygons (OSM-sourced) colour-coded by R-index. Clicking a suburb (or a sidebar row) tilts the camera to 2.5D, zooms in, and reveals 3D building extrusion native to the basemap. A top-r_index suburb gets a permanent pulsing golden ring; every selection fires a screen-projected burst animation; flowing dots travel along the inter-suburb lines as a stand-in for potential exchange capacity.

A small (i) provenance icon next to the suburb name expands a panel showing exactly where that suburb’s data came from — real / partial / SEIFA-approximated — with links to each underlying dataset. The detail card also embeds a live advisor chat that streams Claude responses contextualised to the selected suburb.

The quest board

Five hand-curated EXAMPLE quests load on first paint (one per suburb, each targeting that suburb’s weakest pillar). A single click — “Regenerate with Claude →” — replaces the seed with a fresh AI-generated quest, marked AI , that persists to localStorage so it survives a refresh. Quests generated from the advisor chat appear here too — the two surfaces share state.

The pitch + the admin surface

There’s also /pitch (a long-form editorial walkthrough I built for the hackathon judging panel — Fraunces display type, scroll-paced narrative covering vision, pillars, the data → quest → XP loop, the six agents, honest data provenance, the stack, the roadmap) and /admin (gated on profile.is_admin === true, used to bulk-regenerate every quest with Claude in front of a live audience).

/login has demo personas — pick Maya from Carlton, Tom from Brunswick, Sofia from Footscray, the Admin operator, or play yourself.

3. Real data, transparent AI

This is the bit I’m most proud of.

Real open data with honest provenance

The five suburb pillar scores aren’t made up. They’re pulled by scripts/seed-suburbs.ts from three live Melbourne open-data feeds:

social-indicators-for-city-of-melbourne-residents-2023 (City of Melbourne resident survey)
landmarks-and-places-of-interest (community-facility density within 1.5 km of each centroid)
pedestrian-counting-system-monthly-counts-per-hour (foot traffic → social-connectivity proxy)

Plus ABS 2021 SEIFA IRSD deciles as the fallback for any pillar without a direct signal, and OSM via Nominatim for the boundary polygons.

The catch: data.melbourne.vic.gov.au only covers the City of Melbourne LGA. So of my five demo suburbs, only Carlton has full real data. Fitzroy gets partial coverage (sensors and landmarks reach across the LGA border). Brunswick, Footscray, and Richmond — different LGAs — fall back to SEIFA approximations.

Rather than hide that, I made it the brand. Every suburb’s detail card shows a real / partial / seifa chip with links to the exact datasets used. The /pitch page has a full provenance table. The mock-suburbs.ts file has a per-suburb comment header showing the derivation for the most recent seed run. The schema even has a data_source column on the suburbs table to enforce this at the database level.

The “we tell you what’s real” framing is more interesting than any made-up score.

Glass-box AI

There are six agents in the design (see AGENTS.md); three are wired end-to-end today: Quest Generator (returns one structured JSON quest for a suburb), Initiative Advisor (streaming SSE chat grounded in the selected suburb’s context), and Suburb Narrator (weekly plain-English digest).

Every AI quest card surfaces why it exists, in two layers.

Always visible — the signal strip (amber left-border, between badges and description):

SIGNAL · Claude targeted food security because Carlton scored 27/100 — the lowest of its five pillars.

This is the smallest possible “data → AI choice” lineage: one sentence, one number. The audience sees in plain English which pillar was lowest and why the agent picked it.

Expandable — “How this was created”:

The model name (claude-sonnet-4-20250514)
Generation timestamp
The full input the model saw (suburb · SEIFA · population · season)
The weakest pillar + score (what triggered the choice)
All five pillar scores at generation time as F/S/R/C/E chips
A link to /pitch#provenance for the underlying datasets

The agent endpoint at src/routes/api/quests/+server.ts returns the data_snapshot alongside the quest, the snapshot persists with the quest in localStorage, so refreshing keeps the panel populated. The DB schema already has a data_snapshot jsonb column on the quests table — when Supabase comes online the persistence layer is already aligned.

No vibe-based moderation. Every AI decision is auditable in the UI.

The output discipline is strict: all JSON-returning agents end their system prompt with OUTPUT: Return ONLY valid JSON. and route raw output through a parseAgentJSON() helper that strips accidental json fences before JSON.parse. The advisor is streamed without parsing — its SSE response body pipes straight to the browser. Cost guardrails baked in: max one quest generation per suburb per 24h, narratives cached for 7 days, Matchmaker skipped when the radius is too sparse.

4. The stack, briefly

Frontend — SvelteKit 2 + Svelte 5 with runes mode + TypeScript strict. Svelte 5’s $state / $effect / $derived runes made the reactive flow — store hydration from localStorage, runtime feature-state toggles on the map, the XP-burst on level-up — read cleanly. No external state library.
Map — Google Maps Platform’s WebGL vector renderer with a Map ID configured for tilt + rotation. Pitch 67.5° + heading 20° gives cohesive 2.5D with native 3D building extrusion in the CBD. Polygon overlays sit at zIndex 1000 above the fills; flowing dots are google.maps.Polyline icons stepped via RAF. I tried MapLibre first; it works but the basemap stays flat and our 3D extrusions float — Google’s WebGL vector is the only path to coherent tilt-with-buildings without a custom tile pipeline.
AI — Anthropic Claude (claude-sonnet-4-20250514) called directly from SvelteKit endpoints (streaming SSE for the advisor; JSON-mode for everything else). Cost-guarded.
Open data — data.melbourne.vic.gov.au (Opendatasoft v2.1, anonymous reads) + OpenStreetMap via Nominatim. A one-time fetch script (pnpm fetch:suburb-geo) writes polygon boundaries to a committed JSON file.
Database — Supabase Postgres 15 + PostGIS. Schema + RLS policies fully written (13 SQL migrations) and the typed SupabaseClient<Database> is wired into a per-request server client in hooks.server.ts with a typed-Proxy fallback when env is unconfigured. Provisioning a real Supabase project is one user action away; everything else is offline-complete.
Hosting — Vercel via @sveltejs/adapter-vercel, auto-deploy on push to main. Preview deploys per PR.

5. What’s next

MESH is a 10-sprint roadmap; this hackathon got me to roughly sprint 4. The remaining headline pieces:

Sprint 7 — Submission Verifier. The agent that closes the loop: residents submit photo + text evidence of a completed quest, Claude vision verifies, XP is awarded or routed to a moderation queue.
Sprint 8 — Resource Matchmaker. The agent that powers the “Exchange” in the name. Posts of “I have 10 kg of zucchini” get semantically matched to “I need vegetables for a community kitchen” within a 10 km PostGIS <-> radius, and the mesh edges between matched suburbs light up.
Sprint 10 — Anomaly Watcher. Watches each open-data sync for deltas, classifies them as opportunity / risk / info, and spawns reactive quests or alerts.

The architecture is already shaped to land them quickly once the Supabase project is provisioned. The data-snapshot + transparency pattern I built into the Quest Generator transfers directly to each new agent.

Try it

Live demo → https://mesh-pi-topaz.vercel.app/
Source → https://github.com/furic/mesh
Pitch deck-as-a-page → https://mesh-pi-topaz.vercel.app/pitch

A few things worth clicking:

Sign in as Admin · Demo on /login, then hit “Generate all 5 with Claude →” on /admin. Watch the EXAMPLE chips flip to AI in real time.
On /quests, expand any AI quest’s “How this was created” — the full agent lineage is right there.
On /, click the (i) next to any suburb name to see exactly which datasets fed its scores.

Built in a day for the Claude Impact Lab hackathon (Melbourne, 23 May 2026). Coffee was consumed. Polygons were fetched. AI rationales were strict-JSON-fenced. The streets of Carlton tilted on cue.

The post Building MESH: A Civic Resilience Platform With AI Agents appeared first on Richard Fu.

Unity WebGL Safari Hang: The First-Draw Shader Stall

Richard Fu — Sat, 16 May 2026 07:55:26 +0000

TL;DR — This is a war story about a Unity WebGL Safari hang : a game that ran beautifully on Chrome but froze for ~3 seconds on the first major animation event in iOS Safari. After a long detour through material instancing, shader keywords, animator transitions, and post-FX, the culprit was a single prefab nobody thought to warm up: an overlay spawned by an obscure event handler one frame before the animation started. Mid-game Instantiate of a prefab with a custom shader triggers Safari’s webglPrepareUniformLocationsBeforeFirstDraw on first render — synchronous, main-thread, ~3ms per uniform lookup, ~200 uniforms across a complex prefab = 2.8s stall. The fix is to render the prefab once during the splash so the cache is warm before gameplay needs it.

Reproducing the Unity WebGL Safari Hang

I’m creating a Unity WebGL game with the Universal Render Pipeline (URP) and a lot of custom shaders — particle bursts, dissolve effects, glow overlays, 3D character animations, the works. The target audience is mobile; the majority of players are on iOS Safari, which is exactly where the Unity WebGL Safari hang showed up.

Everything tested fine on desktop Chrome — silky 60fps, fast first interaction, no hitches.

Then we tried Safari on a Mac (and later an iPhone 12). The first major animation event of every session froze the entire game for ~3 seconds. The freeze happened after the build-up animation completed but before the payoff sequence visually started. Every subsequent occurrence of the same event was perfectly smooth.

The pattern was textbook “first-use compile stall”:

Browser	Hang on first event
Chrome (normal)	~0.1s (barely perceptible)
Chrome (incognito, no GPU cache)	~0.2s
Firefox	~2s
Safari (macOS)	~3s
iPhone 12 Safari	~3s

The 25× delta between Chrome and Safari is the smoking gun. Both browsers run Metal under the hood on macOS/iOS — Chrome via ANGLE, Safari directly — but ANGLE aggressively caches shader compilation work that Safari’s WebGL→Metal translator does over and over.

The wrong rabbit holes

Before finding the real cause, we eliminated a long list of suspects through targeted A/B tests. Each took a rebuild + Safari test cycle. Documenting them here in case anyone hits a similar pattern:

A shader keyword toggle. Our main mesh shader uses a [Toggle(_USE_DISSOLVE)] property that activates a fragment-shader branch. Disabling the keyword → hang persisted.
The renderer.material = newInstance assignment. Skipped it on 13 simultaneous objects → hang persisted.
An animator state transition. Commented out the state change that occurred on the same frame → hang persisted.
The entire state handler for the suspect state. Stubbed out the whole switch case → hang persisted.
MMFeedbacks / Feel post-FX (camera shake, vignette). Unsubscribed the handler → hang persisted.
A separate fade-out coroutine on UI overlays. Unsubscribed it → hang persisted.

After all six A/Bs, we’d conclusively ruled out everything on the visible event path. The hang persisted even when the event handler did effectively nothing.

The diagnostic that cracked it

Stopping the guess-and-check loop and capturing a Safari Web Inspector → Timelines profile of the hang was the turning point.

Inside the 3.1-second Animation Frame Fired event, the breakdown was:


wasm-stub 1.94s
  _glGetUniformLocation 906ms (261 calls)
    webglPrepareUniformLocationsBeforeFi… 671ms (194 calls)
      getActiveUniform 444ms (128 calls)
      getProgramParameter 211ms (61 calls)
      getUniformLocation 201ms (58 calls)
  _glGetActiveUniform 423ms (122 calls)
  _glGetActiveUniformsiv 409ms (118 calls)
  _glGetActiveUniformBlockiv 191ms (55 calls)

The 1.94s is Unity’s WebGL runtime asking the browser to look up uniform locations for shader programs it had never drawn before. The remaining ~1.2s of the frame is the actual Metal pipeline-state-object (PSO) compile triggered by the first draw call.

Most importantly: 194 distinct shader programs went through webglPrepareUniformLocationsBeforeFirstDraw in a single frame. That’s not “one or two new variants” — that’s almost the entire scene’s shader inventory being prepared at once.

webglPrepareUniformLocationsBeforeFirstDraw is WebKit-specific. On first draw of a program, it iterates every active uniform, queries the location for each, and caches the mapping. Each call into the WebGL JavaScript API costs ~3ms on Safari (vs ~0.1ms on Chrome’s ANGLE). 200 programs × ~10 calls each at 3ms ≈ 6 seconds of synchronous main-thread work. Spread that across however many programs need preparing on a given frame.

The actual root cause

Once we knew it was first-draw uniform reflection, the question became which prefab is first-drawn on that specific frame. The visible event handler had been stubbed out. Material instancing had been skipped. So what spawned at exactly the right moment?

The game has a server-driven event sequence with several intermediate steps between the trigger and the visible animation. One of those intermediate steps was an “overlay reveal” — a manager that handles a separate server event:


GameObject instance = Instantiate(overlayPrefab, transform);
instance.transform.localPosition = pos;
var overlay = instance.GetComponent&lt;OverlayComponent>();
overlay.SetLevel(level);

A fresh Instantiate, no pool. The overlay’s first draw call happens on the very next render frame after spawn — which on this code path is frame #2 of the next animation’s wait window. The hang at frame #2 matched perfectly. The overlay prefab uses a custom TMP text shader plus a particle/glow combo, with about 200 uniforms across its passes.

Our shader warmup at boot covered the major VFX prefabs we knew about — the burst particles, the highlight glow, the popup labels, the dissolve variant of the main mesh shader. It did not cover this overlay because the manager was an “old” engine system that pre-dated the warmup pattern. Nobody connected the dots: the overlay is spawned by a different event than the animation that hangs, so its first draw appears to be unrelated to the hang location.

Fixing the Unity WebGL Safari Hang

A single line in the overlay manager’s Awake resolved the Unity WebGL Safari hang completely:


using MyGame.Rendering;

protected virtual void Awake()
{
    // ...existing setup...

    if (overlayPrefab != null)
        ShaderWarmup.WarmupPrefab(overlayPrefab);
}

ShaderWarmup.WarmupPrefab does the bare minimum needed to make WebKit compile the program and cache its uniform locations:

Instantiates one copy of the prefab as a child of a WarmupParent transform (parked at the gameplay anchor — wherever the real prefab will spawn in-game, so lighting matches)
Plays any ParticleSystem components so their geometry actually emits this frame
Lets the main camera render the warmup parent for 3 frames during the splash screen — same camera, same lighting state, same render-pass configuration as gameplay, so the PSO key matches
Destroys the throwaway instance

The web front-end’s splash screen waits for both loadProgress >= 1 AND a Unity-side gameReady signal that only fires after every warmup pass has flushed. So the 1-3 seconds of pre-compile work happens behind the loading bar where players already expect to wait, instead of during a critical animation later.

Result on Safari: first event dropped from 3.1s to ~500ms — identical to every subsequent occurrence.

When you need this — and when you don’t

The combination of all three must be true:

Criterion	Need warmup if…
Lifecycle	Prefab is `Instantiate`d at runtime (not present from scene load)
Shader complexity	Uses non-trivial shader: custom `*.shader`, `[Toggle(_KEYWORD)]` properties, `multi_compile` keywords, multi-pass shaders, particle shaders, or TMP shaders with `OUTLINE_ON` / `UNDERLAY_ON` / `BEVEL_ON` variants
Timing	First draw happens during gameplay, not during the loading splash

You don’t need warmup for:

Objects visible from scene load (Unity compiles their shaders during the splash render)
Stock URP Lit/Unlit shaders with no keyword toggles
UI Image components with the default UI shader
Anything that doesn’t render (audio sources, logic GameObjects)

The diagnostic loop

If you suspect this is happening in your game:

Reproduce on Safari , ideally on real hardware. macOS Safari is usually enough — the WebGL-via-Metal path is the same.
Open Web Inspector → Timelines tab. Hit record, trigger the event that hangs, stop recording.
Find the long frame in the JavaScript & Events row.
Look under wasm-stub for high counts of _glGetUniformLocation, _glGetActiveUniform, webglPrepareUniformLocationsBeforeFirstDraw. If you see dozens or hundreds of these on one frame, you’ve found a first-use shader event.
Identify what’s first-rendered. What prefab spawned recently? What keyword was toggled? What material was instanced?
Add a ShaderWarmup.WarmupPrefab call in that subsystem’s Awake.

A subtle gotcha: the prefab that causes the hang may not be the one whose animation is running when the hang happens. In our case the overlay was spawned by a completely separate event handler one frame before the visible animation started, so the hang appeared to be inside the animation. Trace recent Instantiate calls backward from the slow frame, not just what’s animating during it.

Related prior art

The general “WebGL on Safari is slow at things ANGLE handles fast” story is well-documented:

WebGL Performance on Safari and Apple Vision Pro — Wonderland Engine describes a ~150ms hitch from Safari’s Metal-emulated uniform buffer uploads. Same family of issues at a smaller scale.
WebKit Bug 218949 — WebGL instanced draw calls slow on iPhone 12 Pro
WebKit Bug 230749 — WebGL performance regression on particles in Safari 15
WebKit Bug 239015 — Performance regression after uploading WebGL buffers (Safari 15.4)
Unity Manual: Prewarm shaders — official docs explicitly note that Shader.WarmupAllShaders may not warm correctly on Metal/Vulkan because vertex layout differs from the actual draw call, which is exactly why we render through the main camera rather than calling WarmupAllShaders.
Unity Forum: Shader Compile Frame Hitches even with Shader.WarmupAllShaders — confirms the official API doesn’t fully solve the problem
Unity WebGL tips / advice in 2023 — Radiator Blog — general WebGL gotchas

The specific case that bit us — a prefab Instantiated mid-game by an obscure event handler, whose first draw lands inside an unrelated critical animation one frame later — isn’t covered in the existing material. The Safari Web Inspector webglPrepareUniformLocations* markers as a diagnostic tool also seem underused; I didn’t find any reference to using them for Unity WebGL debugging.

Takeaways

Shader.WarmupAllShaders is not enough on Metal/Vulkan. You have to actually render the geometry through the same camera pipeline that gameplay will use.
The first draw call of any custom-shader prefab is expensive on Safari. Plan for it. Render once during the splash. Engineering effort: one line per missed prefab.
Self-registering warmup is the right pattern. Each subsystem that spawns prefabs at runtime should warm its own prefab in Awake instead of relying on a central registry. New systems get coverage automatically without anyone remembering to wire them up.
Diagnose with the Safari profiler, not by guessing. We burned a full day on A/B isolation before realizing the answer was sitting in the Web Inspector timeline the whole time. The webglPrepareUniformLocations* markers tell you exactly when first-use uniform discovery is happening — search for them.
Pool spawned prefabs aren’t a substitute for warmup. Pooling avoids Instantiate allocation cost (microseconds). Warmup avoids first-draw shader compile cost (seconds). They solve different problems and you typically want both.

If your Unity WebGL game has a “first time something happens” hitch on Safari that doesn’t repeat, you’re almost certainly looking at a Unity WebGL Safari hang of the same family. The Safari profile + webglPrepareUniformLocationsBeforeFirstDraw markers are the fastest path to the answer. Hope this saves someone a long debugging session.

The post Unity WebGL Safari Hang: The First-Draw Shader Stall appeared first on Richard Fu.

Re-skinning a 3D Character with AI Image Tools (Without Touching Blender)

Richard Fu — Sat, 02 May 2026 15:58:20 +0000

TL;DR: I bought a well-made chibi farmer model and wanted to reuse it as a zookeeper character — same mesh, same rig, same animations. Meshy.ai’s Retexture didn’t work for me, and naive cropping of the UV atlas pulled in neighbor pieces. The fix turned out to be embarrassingly simple: connected-component labeling to extract one UV island at a time, send each piece to ChatGPT with a tight prompt, then composite the AI result back with an intersection-of-silhouettes mask. I packaged the workflow as a Claude Code skill — furic/texture-atlas-roundtrip — and ended up with a wildlife keeper that took a couple of evenings instead of a couple of weeks.

The problem

I’m a developer with no artist skills. For my causal game prototype, I needed a wildlife keeper character. I’d already paid for a beautifully animated chibi farmer (Suriyun’s Farmer SD pack), and the rig + animations were exactly what I wanted. The catch: the outfit was a plaid shirt + denim jeans + straw hat with a red band. Pure farmer.

What I needed:

A khaki keeper shirt with chest pockets
Khaki cargo pants/shorts
A pith helmet instead of a straw hat
Brown leather boots

What I wanted to not do:

Touch the FBX, the rig, or any animation
Open Blender to re-UV anything
Hand-paint a 2048×2048 texture from scratch

The character has one big packed texture atlas — Famer.png — with the shirt front, shirt back, sleeves, pants, belt, hat, leather accessories, and a few small bits all unwrapped onto a single image. That single PNG is what I needed to modify.

What didn’t work

Meshy.ai’s retexture function. I uploaded the FBX and tried both “text input” and “image input” prompts. The results were unrecognizable — colors smeared in the wrong places, details bleeding across UV seams. It felt like the model wasn’t understanding the UV mapping of the imported asset. Maybe there’s a config I missed, but I didn’t dig in: a one-click solution will probably exist in 12 months, but right now it doesn’t.

Asking ChatGPT to redraw the whole atlas. DALL-E doesn’t preserve UV island shapes pixel-precisely. Even with a strict “keep dimensions, keep silhouette” prompt, you get back a texture that looks roughly right but seams shift, the hat brim rotates 5°, the collar moves. UV-bound textures are unforgiving — even a few-pixel shift causes visible artifacts on the 3D mesh.

Cropping a single piece out as a rectangle. The atlas packs UV islands tightly to save memory, so the shirt-front bbox always includes slivers of the belt above and the suspender stripes that are technically in the same connected pixel region. Sending that to AI and pasting back contaminated the neighbor pieces.

So the path forward needed to be: edit one piece at a time, keep its silhouette pixel-perfect, and protect everything else from collateral damage.

The solution: split → edit → composite

The technique has three parts, and only the splitting bit is non-obvious:

Split the atlas into per-UV-island PNGs. Each piece is a 1024×1024 canvas with one island centered and everything else (including neighbor islands that share its bbox) masked to pure black.
Edit each piece independently in any AI image tool. Because the background is solid black, the AI has a clean canvas and won’t draw beyond the island silhouette.
Composite the AI’s result back into the atlas at the exact original pixel coordinates, using a mask that protects neighbor islands from accidental overwrites.

Why naive cropping fails — and what to do instead

The atlas has roughly nine clearly visible UV islands, but they sit close together in the 2D image:

+-------------------------------+
|                               |
|   [BELT — wide horizontal]    |
|                               |
|  [SHIRT FRONT]   [SHIRT BACK] |
|                               |
|                  [SLEEVES][..]|
|                               |
|  [PANTS]        [STRAW HAT]   |
|                               |
+-------------------------------+

If I rectangle-crop “shirt front”, I’m guaranteed to also catch a slice of the belt above it or the leather puffs on its right edge. Send that to AI, and the AI either repaints those slivers (corrupting the belt) or, more often, fills them with black — and “fills with black” is exactly what destroys the belt when I paste back.

The fix is to extract the connected component rather than a rectangle. scipy.ndimage.label walks the image, assigns each contiguous non-black region its own integer ID, and gives you a per-pixel labels array. Then I crop the bbox AND zero every pixel whose label isn’t the one I want:

import numpy as np
from PIL import Image
from scipy import ndimage

img = np.array(Image.open("atlas.png").convert("RGBA"))
non_black = img[..., :3].sum(-1) > 30   # tolerate near-black gradients

labels, n = ndimage.label(non_black)
sizes = ndimage.sum(non_black, labels, range(1, n + 1))
slices = ndimage.find_objects(labels)

# Pick the island we want (e.g. by bbox heuristic or label_id)
target_label = 5
y0, y1 = slices[target_label - 1][0].start, slices[target_label - 1][0].stop
x0, x1 = slices[target_label - 1][1].start, slices[target_label - 1][1].stop

# Extract just this island — neighbors masked to black
piece = img[y0:y1, x0:x1].copy()
mask = labels[y0:y1, x0:x1] == target_label
piece[~mask] = [0, 0, 0, 255]

Now I have a piece I can drop onto a 1024×1024 black canvas, save out as shirt_front.png, and hand to any AI tool with a clean conscience.

I also save a manifest.json recording each piece’s original src_bbox, canvas_offset, label_id, and (we’ll come back to this) flip_y. The manifest is what makes the round trip work — without it, pasting back at the exact pixel position is guesswork.

The intersection-of-silhouettes paste-back

When the AI returns its result, the obvious composite is “paste the whole AI image into the original bbox.” But there are two failure modes hiding in there:

Failure 1: AI’s pure-black background covers neighbor islands that happen to fall inside the bbox. Belt fragment that lived in the corner of the shirt-front bbox? Now black.
Failure 2: AI drew slightly outside the original silhouette (e.g. extended the shirt by 5px on the left). Those extra pixels land on parts of the texture that map to invisible mesh — but worse, they can land on a different UV island in the same bbox.

The fix is the intersection of two silhouettes:

# AI silhouette: where the AI actually drew content
ai_silhouette = ai_result.sum(-1) > 30

# Original silhouette: where the target UV island lives in the atlas
src_labels, _ = ndimage.label(original_atlas.sum(-1) > 30)
orig_silhouette = src_labels[y0:y1, x0:x1] == target_label

# Paste only where both agree
mask = ai_silhouette & orig_silhouette
target[y0:y1, x0:x1][mask] = ai_resized[mask]

Original-silhouette-only would let AI black overwrite neighbors. AI-silhouette-only would let AI bleed onto invisible mesh. The intersection covers both directions in one line.

I add a tiny erosion + Gaussian blur on the mask to avoid hard edges where AI’s stroke meets the existing texture. That single trick is what makes the round trip clean enough to ship.

The Y-flip gotcha

I sent shirt_front.png to ChatGPT with a careful prompt — “khaki shirt, two chest pockets, keep dimensions and silhouette” — and got back an excellent result. Pasted it back, opened Unity, and the pockets were on the keeper’s waist. Upside down.

Took me a minute to figure out why: the chibi character’s UV unwrap stores the shirt vertically flipped relative to mesh space. The V-notch at the bottom of the texture? That’s the collar in 3D. When the AI looked at the piece, it saw a normal shirt right-way-up (because the collar happens to point down in the texture) and drew pockets in the upper half. Those pockets, mapped back to mesh, landed on the lower torso.

The fix has two flavors:

Flavor A — don’t pre-flip; flip the AI result during composite.
Pockets will still be in the wrong half of the canvas, but the second flip puts them on the chest. Works for symmetric content.

Flavor B — pre-flip the input so AI works in natural orientation.
Send a Y-flipped piece to AI, AI draws on a “right-side-up” shirt, then composite flips the result back. Two flips total. Better for asymmetric content (name tags, logos).

I went with Flavor B and added a flip_y: true field to the manifest entry for each Y-flipped piece. The composite step honors it automatically:

if effective_flip_y:
    edited_pil = edited_pil.transpose(Image.FLIP_TOP_BOTTOM)

Discovery flow: composite once, see that pockets are upside-down, set flip_y: true in the manifest, re-composite. No re-prompting needed.

The workflow in practice

Here’s the actual loop I ran for the keeper conversion:

SKILL=~/.claude/skills/texture-atlas-roundtrip

# 1. Split the farmer atlas into per-UV-island PNGs
python3 $SKILL/split.py Famer.png ./pieces/

# 2. Rename pieces in manifest.json (island_2 → shirt_front, etc.)
#    Mark Y-flipped pieces: "flip_y": true

# 3. (For Y-flipped pieces) pre-flip so AI sees natural orientation
python3 $SKILL/flip_piece.py shirt_front.png  # → shirt_front_flipped.png

# 4. Send each piece to ChatGPT with a prompt like:
#    "Redraw this UV texture as a khaki keeper shirt with two chest pockets,
#     keep 1024×1024 dimensions, pure black background, exact silhouette..."
#    Save the result back to the same filename.

# 5. Composite each edited piece into the keeper atlas
python3 $SKILL/composite.py M07_Keeper.png shirt_front shirt_front_edited.png ./pieces/manifest.json

For the hat I used a slightly different sub-flow: extract the hat region with the connected-component mask, send to ChatGPT with a pith-helmet reference photo and a “top-down circular UV” prompt, composite back. Since the existing straw hat already had the right round silhouette for a top-down dome+brim view, AI just had to repaint the texture inside that silhouette — no UV alignment risk.

Pants had one extra wrinkle: the “pants” UV island is actually pants AND boots in one piece, with a visible curve dividing them. After the first AI pass turned the whole island into khaki, the boots came out as khaki socks. Second pass with a “modify only below the curve” prompt added brown leather boots without disturbing the pants area.

Results

Before:

After:

The model, rig, animations, and FBX are completely untouched. The keeper texture is a single recolored + AI-edited variant of Famer.png, drop-in compatible with the original material.

For comparison, here’s Meshy.ai’s attempt — which is what pushed me to build this in the first place:

Get the skill

I packaged the workflow as a Claude Code skill: furic/texture-atlas-roundtrip.

git clone https://github.com/furic/texture-atlas-roundtrip ~/.claude/skills/texture-atlas-roundtrip
pip install numpy Pillow scipy

The repo includes:

SKILL.md — when to use, common mistakes, paste-back masking logic
split.py — atlas → per-island PNGs + manifest
composite.py — paste-back with intersection mask + Y-flip support
flip_piece.py — vertical flip helper for Y-flipped UVs
examples/ — optional /split-texture and /merge-texture slash command shortcuts

Roughly 200 lines of Python total. The whole thing exists because connected-component labeling solves an entire class of UV editing problems if you let it.

What I’d want next

A model-aware AI image tool that understands the UV → mesh mapping would make all of this obsolete. Meshy.ai’s retexture is the closest thing today and it didn’t work for my chibi character; presumably it’ll be solved in the next round. Until then, splitting an atlas and round-tripping pieces through ChatGPT is the most reliable workflow I’ve found, and it’s good enough that I’m planning to use it for the next four characters in this series.

If you’ve been blocked on reskinning a 3D asset because you’re not an artist, give the skill a try and tell me where it falls down — issues and PRs welcome at the repo.

The post Re-skinning a 3D Character with AI Image Tools (Without Touching Blender) appeared first on Richard Fu.

Building “Unmask the City” – A Solo Game Jam Journey with AI Pair Programming

Richard Fu — Sat, 31 Jan 2026 10:21:51 +0000

Another Year, Another Solo Jam

It’s Global Game Jam season again, and once again I found myself diving in solo. But this year was different – I had a new coding partner: Claude Code.

The theme for GGJ 2026 was “Mask”. While others might build games about literal masks – masquerades, disguises, hidden identities – I saw something different. What if the mask wasn’t on a person, but on an entire city? What if you had to “unmask” a fog-shrouded metropolis by exploring it?

That’s how Unmask the City was born.

The Challenge: Vibe Coding from Zero

I set myself an ambitious constraint: build everything from scratch. No templates. No pre-made 3D models. No asset packs. Just code, procedural generation, and pure vibes.

Why? Because I wanted to see how far modern web technologies could take me in a game jam timeframe when paired with AI assistance. Could we create something that feels complete, polished, and technically impressive using only:

Three.js primitives (boxes, cylinders, spheres)
Procedural audio (Web Audio API)
Custom shaders
A lot of mathematical creativity

Spoiler: We did. And it was wild.

The Game: Exploring the Unknown

Concept: You’re dropped into a procedurally generated city consumed by a malevolent fog. Ancient fragments of light are scattered throughout – collect them all to unmask the city and reveal its secrets.

Core Mechanic: Permanent fog clearing. Everywhere you walk, the fog disappears forever, creating a visual record of your exploration. It’s like drawing a map with your presence.

Goal: Find all fragments in the shortest time while exploring as much of the city as possible. Three difficulty levels scale the challenge (5/7/10 fragments).

Simple premise, but the execution is where things got interesting.

Tech Stack: Modern Web at Its Best

Three.js – The Rendering Engine

I chose Three.js because it’s the mature, battle-tested 3D engine for the web. Version 0.170.0 gave me:

WebGL 2.0 rendering
Built-in shadow mapping
Excellent primitive geometries
PointerLockControls for FPS gameplay

But the real power move? InstancedMesh. Instead of rendering 300 buildings with 300 draw calls, I render them all with 1-2 draw calls. That’s a 150x performance improvement right there.

TypeScript – Sanity in the Chaos

Game jams are chaotic. Code gets messy fast. TypeScript was my safety net:

Catch bugs at compile time, not at 3 AM during playtesting
IDE autocomplete saves so much time
Interfaces make the codebase self-documenting

Every game entity (Building, Tree, Fragment, Park) has a typed interface. When you’re iterating fast, this type safety prevents entire categories of bugs.

Vite – The Secret Weapon

Vite’s Hot Module Replacement is insane for game development:

Change shader code → see results in 100ms
Adjust particle parameters → particles update live
Modify audio synthesis → sounds regenerate instantly

No rebuild. No refresh. Just pure flow state.

Web Audio API – Zero Asset Files

Here’s where it gets interesting: every sound in the game is procedurally generated. No MP3s. No WAV files. Pure synthesis:

Footsteps: Filtered noise with different characteristics per surface (concrete, grass, water)
Fragment collection: Musical arpeggios (different chord progressions per fragment type)
Ambient sounds: Wind, water, traffic, night creatures (crickets, owls)
Spatial audio: Echo and reverb that adapts to building proximity

Why procedural? Because:

Instant iteration (tweak a frequency, hear it immediately)
Zero load times (no files to download)
Infinite variation (sounds never repeat exactly)
Smaller bundle size

The entire audio system fits in one TypeScript file and sounds better than most asset-pack audio.

The Build: From Void to Playable in Hours

Day 1: Foundation & Core Loop

Morning: Set up the Three.js scene, camera, and basic player controls. Implemented the fog-of-war system using a DataTexture – a 512×512 texture that tracks which areas you’ve explored.

Why DataTexture? Alternative approaches:

Per-vertex fog checks: Too expensive
Raymarching in shader: GPU bottleneck
DataTexture: Paint on CPU, sample on GPU. Perfect.

Afternoon: Procedural city generation. Grid-based layout with randomized:

Building dimensions (8-20 units wide, 15-100+ tall)
Building types (box, cylinder, L-shaped)
Rooftop details (antennas, water towers, helipads, gardens)
Buildings get taller toward the center for visual interest

Evening: Collectibles and collision detection. Simple 2D AABB collision (buildings are axis-aligned, player is a capsule). Fragment spawning with validation to avoid placing them inside buildings.

Status: Technically playable, but ugly and silent.

Day 2: Polish, Polish, Polish

This is where Claude Code really shined. Instead of spending hours debugging or looking up APIs, I could:

Me: “Add surface-specific footstep sounds”

Claude: Generates complete Web Audio implementation with concrete, grass, and water variations

Me: “The trees look static, add some life”

Claude: Implements vertex shader wind animation with multi-frequency sine waves

Me: “Fragments need more juice when collected”

Claude: Adds particle burst, screen color tint, slow-motion effect, and camera shake

By afternoon, I had:

Four visual themes (Day → Dusk → Night → Neon) on auto-cycle
Particle systems (birds, clouds, leaves, steam, embers)
Spatial audio with echo effects
A complete UI with loading screen, start menu, and game info modal

By evening:

Glowing breadcrumb trail showing your path
Fireworks victory sequence
Local leaderboard with multiple scoring bonuses
Screenshot capture (P key)

The game went from “functional prototype” to “feels AAA” in a single day.

Technical Deep Dives & Code Highlight

Custom Shader Injection

Buildings need to react to the fog of war texture, but I didn’t want to write a full custom shader (losing Three.js’s nice PBR lighting). Solution? onBeforeCompile:


material.onBeforeCompile = (shader) => {
  // Add custom uniforms
  shader.uniforms.fogMap = { value: fogTexture };

  // Inject custom fragment shader code
  shader.fragmentShader = shader.fragmentShader.replace(
    '#include <fog_fragment>',
    `
    // Sample fog texture
    vec2 fogUV = (worldPos.xz + cityBounds.xy) / cityBounds.zw;
    float fogDensity = texture2D(fogMap, fogUV).r / 255.0;

    // Darken buildings in fogged areas
    gl_FragColor.rgb = mix(gl_FragColor.rgb, vec3(0.3), fogDensity * 0.9);

    #include <fog_fragment>
    `
  );
};

This lets me keep Three.js’s lighting while adding custom fog behavior. And it works with InstancedMesh!

Instanced Rendering – 150x Performance Boost

Instead of:


// BAD: 300 draw calls
buildings.forEach(building => {
  const mesh = new THREE.Mesh(geometry, material);
  mesh.position.copy(building.position);
  scene.add(mesh);
});

I use:


// GOOD: 1 draw call
const instancedMesh = new THREE.InstancedMesh(geometry, material, 300);
buildings.forEach((building, i) => {
  const matrix = new THREE.Matrix4();
  matrix.compose(building.position, rotation, building.scale);
  instancedMesh.setMatrixAt(i, matrix);
  instancedMesh.setColorAt(i, building.color);
});

Result: Smooth 60 FPS with 300+ buildings, shadows, and particles.

Compass Logic – Finding Nearest Fragment

The HUD compass always points to the nearest uncollected fragment:


// Find nearest fragment
let nearest = uncollected[0];
let minDist = Infinity;

uncollected.forEach(fragment => {
  const dist = playerPos.distanceTo(fragment.getPosition());
  if (dist < minDist) {
    minDist = dist;
    nearest = fragment;
  }
});

// Calculate angle and rotate compass arrow
const dx = nearest.getPosition().x - playerPos.x;
const dz = nearest.getPosition().z - playerPos.z;
const angle = Math.atan2(dx, dz);

compassElement.style.transform = `rotate(${angle}rad)`;

No pathfinding needed – just point toward the goal. Players love it.

Procedural Thunder – Layered Noise Synthesis

Thunder isn’t just random noise. It’s carefully crafted with rumble + crack:


playThunder() {
  const data = buffer.getChannelData(0);

  for (let i = 0; i < data.length; i++) {
    const t = i / sampleRate;

    // Envelope: quick attack, slow decay
    const env = Math.exp(-t * 1.5) * (1 - Math.exp(-t * 20));

    // Low-frequency rumble
    const rumble = Math.sin(t * 30 + Math.random() * 0.5) * 0.5;

    // High-frequency crack
    const crack = (Math.random() * 2 - 1);

    // Mix and apply envelope
    data[i] = (rumble + crack * 0.5) * env;
  }

  // Low-pass filter for deep rumble
  filter.type = 'lowpass';
  filter.frequency.value = 200 + Math.random() * 100;
}

Real thunder has that rumble + crack quality. This captures it with pure math.

Minimap – Coordinate Mapping

Map world coordinates to minimap percentage for CSS positioning:


function worldToMinimapPercent(worldPos: Vector3): { x: number, y: number } {
  const citySize = 400; // World spans -200 to +200

  // Normalize to 0-1, then convert to percentage
  const normalizedX = (worldPos.x + citySize / 2) / citySize;
  const normalizedZ = (worldPos.z + citySize / 2) / citySize;

  return { x: normalizedX * 100, y: normalizedZ * 100 };
}

// Position fragment dots
dot.style.left = `${pos.x}%`;
dot.style.top = `${pos.y}%`;

Same technique used for fog texture UVs. Master coordinate mapping once, use it everywhere.

Fireworks Physics – Spherical Particle Distribution


explode(position: Vector3) {
  for (let i = 0; i < particleCount; i++) {
    // Random direction on sphere
    const theta = Math.random() * Math.PI * 2;
    const phi = Math.random() * Math.PI;

    const velocity = new Vector3(
      Math.sin(phi) * Math.cos(theta),
      Math.sin(phi) * Math.sin(theta),
      Math.cos(phi)
    ).multiplyScalar(8 + Math.random() * 4);

    particles.push({ position, velocity, life: 1.0 });
  }
}

update(delta: number) {
  particles.forEach(p => {
    p.position.add(p.velocity.clone().multiplyScalar(delta));
    p.velocity.y += -9.8 * delta; // Gravity
    p.life -= delta * 0.5; // Fade
  });
}

Spherical distribution + gravity = convincing fireworks. No physics engine needed.

Challenges & Lessons Learned

Challenge 1: The Tree Gap Bug

Problem: Trees had separate trunk and crown meshes. When I added wind animation to crowns (vertex shader), visible gaps appeared during sway.

Attempts:

Increase overlap → Still visible
Merge geometries with vertex attributes → Broke colors
Reduce animation → Still janky

Solution: Disable wind animation entirely. Static trees look fine and the gap is gone. Sometimes the best solution is the simplest one.

Lesson: Don’t over-engineer. If a feature causes more problems than it solves, cut it.

Challenge 2: Fragment Spawning

Problem: Fragments occasionally spawned inside buildings or in unreachable locations.

Evolution:

v1: 2-unit clearance → Too close to buildings
v2: 12-unit clearance → Better but still issues
v3: 20-unit clearance + disabled problematic building types (pyramids, domes)
v4: 30-unit clearance + increased collection radius

Lesson: Incremental fixes are okay. Don’t wait for the “perfect” solution.

Challenge 3: Performance vs. Visual Fidelity

Constraint: Browser game running at 60 FPS with no stutters.

Decisions:

Instanced rendering for buildings (✓ massive win)
Shadow map resolution: 2048×2048 (sweet spot)
Particle count: Dynamic based on system type
Fog texture: 512×512 (could go lower, but 256 KB is negligible)
LOD system: Not needed (instancing is enough)

Lesson: Profile before optimizing. Instancing alone solved 90% of performance concerns.

Working with Claude Code

This was my first game jam with AI pair programming. Here’s what that looked like:

What Worked Really Well

1. Rapid prototyping

Me: “Add thunder sounds for lightning”

Claude: Complete Web Audio implementation with rumble, crack, and realistic delay

Time saved: 30-60 minutes per feature

2. Bug fixing

Me: “Fireworks particles aren’t cleaning up”

Claude: Identifies the issue, implements proper disposal in filter callback

3. Polish iterations

Me: “Make the breadcrumb trail look nicer”

Claude: Converts from thin lines to glowing tube geometry with particles

What Required Guidance

1. Creative decisions

Claude can implement, but vision is still human. I had to decide:

How fog should look (teal with corruption hints)
What themes to include (day/dusk/night/neon)
Which features to cut when time was tight

2. Bug investigation

Complex visual bugs (like the tree gap) required back-and-forth. Claude would suggest fixes, I’d test, we’d iterate.

3. Performance tuning

Deciding what to optimize required understanding the bottleneck. Claude implemented solutions once I identified the problem.

The Workflow

Typical flow:

I describe what I want (feature or fix)
Claude implements it
I test in the browser (Vite HMR makes this instant)
If issues, I describe what’s wrong
Claude iterates

It’s like having a senior developer who:

Never gets tired
Remembers every file in the codebase
Writes clean, well-commented code
Doesn’t argue about architecture decisions

But I’m still the director. The creative vision, gameplay feel, and final polish decisions are mine.

The Numbers

Development Stats:

Time: 1.5 intensive days (+ polish sessions)
Code: ~3,700 lines of TypeScript
Commits: 15+ (after cleaning up the messy ones)
External dependencies: 1 (Three.js)
External assets: 0 (everything procedural)

Technical Achievements:

300+ procedurally generated buildings
100% procedural audio (zero sound files)
60 FPS on modern hardware
~500 KB bundle size (gzipped)
Zero load times (no assets to fetch)

Game Content:

3 difficulty levels
4 dynamic visual themes
5 particle systems
20+ game systems/classes
Multiple scoring bonuses
Local leaderboard

Key Takeaways

1. Procedural Generation is Powerful

No 3D models meant:

Instant iteration (change a parameter, see results)
Infinite variety (every city is unique)
Tiny bundle size
Creative constraints that forced innovation

The visual aesthetic emerged from the limitations. Low-poly geometric buildings with procedural color variation created a distinctive look.

2. Web Audio API is Underrated

Game devs sleep on Web Audio API. Yes, it’s more work than dropping in an MP3. But:

Sounds can react to gameplay dynamically
Zero licensing concerns
No asset management overhead
Perfect for game jams where time > polish

Surface-specific footsteps and spatial echo effects make the world feel alive.

3. Vite’s HMR is a Game Changer

The feedback loop is everything in game development. Vite made it:

Edit shader → 100ms to see change
Adjust physics → instant update
Modify UI → no page refresh

Traditional build tools would have killed my momentum.

4. AI Pair Programming Accelerates Flow

Claude Code didn’t replace my skills – it amplified them. I could:

Stay in creative flow (no context switching to docs)
Iterate faster (implement → test → refine)
Tackle ambitious features (spatial audio, custom shaders)
Focus on design while AI handles implementation

The result: A scope I would normally consider impossible for a solo jam.

5. Constraints Breed Creativity

“No external assets” forced me to:

Master procedural generation
Learn Web Audio API deeply
Think in primitives and compositions
Build systems instead of placing objects

These constraints made the game more interesting, not less.

What I’d Do Differently

1. Test on Different Machines Sooner

I developed on a beefy machine. Didn’t test on lower-end hardware until late. Luckily, instanced rendering meant performance was fine, but that was lucky – not planned.

2. Implement Settings Menu

Audio volume, mouse sensitivity, graphics quality – these should have been in from the start. Players expect them. I shipped without them due to time constraints.

3. Better Spawn Validation from Day One

The fragment spawning issues ate more time than they should have. A robust validation system upfront would have saved iterations.

Unexpected Wins

1. The Breadcrumb Trail

Initially just a debug feature to see where I’d been. Players loved it so much I polished it:

Thin lines → Glowing tube geometry
Static → Particle sparkles
Flat → Elevated with smooth curves

Became one of the game’s signature visual elements.

2. Automatic Theme Cycling

Originally, themes were manual (press T to cycle). Making it automatic with smooth cross-fades created this living, breathing atmosphere. The city feels different every few minutes.

3. Procedural Audio Reactions

Making audio react to environment (echo in tight spaces, wind in open areas) was a last-minute addition. It’s subtle but makes the world feel responsive and real.

The Verdict: Did Vibe Coding Work?

Yes.

I shipped a complete 3D exploration game with:

✅ Procedurally generated world
✅ Complete audio design (100% procedural)
✅ Four visual themes with smooth transitions
✅ Multiple particle systems
✅ Professional UI with loading screens, menus, and HUD
✅ Scoring system with bonuses
✅ Local leaderboards
✅ Victory celebration sequence
✅ Comprehensive documentation
✅ Clean codebase (~3,700 lines)

Zero external assets. Zero templates. Just code, creativity, and AI assistance.

Would it have been possible solo without Claude? Sure – but it would have taken a week, not two days. And I would have cut half the features.

For Future Game Jammers

If you’re considering AI-assisted development for your next jam:

Do This:

Use AI for implementation, not vision
Iterate fast (test → feedback → refine)
Let AI handle boilerplate and documentation
Stay in flow state (avoid context switching)
Focus on creative decisions

Don’t Do This:

Accept AI suggestions blindly
Skip testing (“it compiled, ship it”)
Outsource all problem-solving
Forget that you’re still the designer

The Real Benefit

It’s not that AI writes code faster (though it does). It’s that you can stay in creative flow. No googling APIs. No context switching to documentation. No “how do I implement X” rabbit holes.

You think of a feature, describe it, and boom – it exists. Then you playtest, refine, polish.

That’s the game jam superpower.

Play the Game

Live demo: https://furic.github.io/unmask-the-city/

GGJ page: https://globalgamejam.org/games/2026/unmask-city-4

Source code: https://github.com/furic/unmask-the-city

Tech stack docs: See TECH_STACK.md in the repo

Built for Global Game Jam 2026 | Theme: Mask

Developer: Richard Fu / fuR Gaming

AI Pair Programming: Claude Code

Final Thoughts

Game jams are about constraints, creativity, and controlled chaos. This year, I added a new constraint: no external assets. And a new tool: AI pair programming.

The result surprised me. Not just in scope (way bigger than I expected), but in polish. The game feels complete. Menus, sound, particles, themes, documentation – all the things you usually sacrifice in a jam.

Is this the future of solo game development? Maybe. At minimum, it’s a glimpse of how AI tools can amplify individual creativity instead of replacing it.

Would I do it again? Absolutely.

Next jam, I’m going even bigger. 🎮

P.S. – If you’re curious about specific technical implementations (shader code, audio synthesis, procedural generation algorithms), check out the full technical documentation in the repo. It’s a deep dive into every technique used.

The post Building “Unmask the City” – A Solo Game Jam Journey with AI Pair Programming appeared first on Richard Fu.

Building Bubble 2048: A Technical Deep Dive

Richard Fu — Sat, 24 Jan 2026 14:20:13 +0000

When I participated in Global Game Jam 2025 with the theme “Bubble,” I wanted to create something familiar yet innovative. The result? Bubble 2048 – a twist on the classic 2048 puzzle game where tiles don’t just slide… they bubble up.

But here’s the thing: I didn’t finish it during the jam last year. Life got in the way, and the project sat incomplete for nearly a year. Then, just before Global Game Jam 2026 kicked off, I discovered Claude Code – and everything changed. What had been a frustrating tangle of animation bugs and timing issues became manageable. With Claude’s help debugging the animation system and refining the game logic, I finally completed what I’d started at GGJ 2025, just in time to approach this year’s jam with renewed confidence.

Play the game here | GitHub Repository

The Unique Mechanic: Double Movement System

The game’s defining feature is its dual-movement mechanic. Unlike classic 2048 where you make a move and wait for the next tile to spawn, Bubble 2048 adds a second layer:

Player Move : Swipe in any direction (up, down, left, or right) – tiles slide and merge as expected
Bubble Shift : After your move completes, ALL tiles automatically shift upward by one row (like bubbles rising in water), with another merge opportunity
Spawn : Only after both movements complete does a new tile appear

This creates a fascinating strategic depth – you’re not just planning one move ahead, but considering how the automatic bubble shift will affect your board state.

Tech Stack: Simple but Effective

I kept the technology stack deliberately minimal:

React 19 with TypeScript for type safety and component structure
Vite for lightning-fast development and optimized builds
Pure CSS animations for all visual effects (no animation libraries needed)
Zero game engine dependencies – all game logic written from scratch

The entire project uses only 2 production dependencies: react and react-dom. Everything else is built in-house.

Game Logic Architecture

Grid State Management

The game state is built around a clean TypeScript interface:


interface Tile {
  id: string; // Unique identifier
  value: number; // 2, 4, 8, 16, 32...
  position: Position; // Current { row, col }
  previousPosition?: Position; // For slide animations
  mergedFrom?: [Tile, Tile]; // Which two tiles merged
  isNew?: boolean; // For spawn animation
}

type Grid = (Tile | null)[][]; // 4x4 array

This structure supports everything needed for animations: we track where tiles came from (previousPosition), which tiles merged together (mergedFrom), and which just spawned (isNew).

The Movement Algorithm

The core movement logic (moveTiles) processes tiles in the correct traversal order. For right/down movements, we reverse the iteration to prevent tiles from “leap-frogging” during merges:


function getTraversalOrder(direction: Direction) {
  const rows = [0, 1, 2, 3];
  const cols = [0, 1, 2, 3];

  if (direction === 'down') rows.reverse();
  if (direction === 'right') cols.reverse();

  return { rows, cols };
}

The algorithm:

Iterate through tiles in traversal order
For each tile, find the farthest position it can move to
Check if the destination contains a tile with the same value
If yes and it hasn’t merged yet → merge them (create new tile with doubled value)
If no → just move the tile
Track merged positions to prevent double-merging

The crucial anti-double-merge logic uses a Set:


const mergedTiles = new Set<string>();

// When checking if we can merge
if (next && next.value === tile.value && !mergedTiles.has(nextPosKey)) {
  // Merge and mark position
  mergedTiles.add(nextPosKey);
}

The Bubble Mechanic

The bubble shift is simpler than player movement – it only moves upward and doesn’t cascade through multiple empty cells:


function bubbleShiftUp(grid: Grid): MoveResult {
  // Process rows from top to bottom (skip row 0)
  for (let row = 1; row < GRID_SIZE; row++) {
    for (let col = 0; col < GRID_SIZE; col++) {
      const tile = grid[row][col];
      if (!tile) continue;

      const aboveRow = row - 1;
      const aboveTile = grid[aboveRow][col];

      if (!aboveTile) {
        // Move up to empty space
        moveTileToPosition(tile, aboveRow, col);
      } else if (aboveTile.value === tile.value) {
        // Merge with tile above
        mergeTiles(aboveTile, tile);
      }
    }
  }
}

This intentional simplicity prevents infinite cascade scenarios while still providing strategic depth.

The Animation Challenges

Getting smooth animations working was the most challenging part of the project – and honestly, what kept me from finishing during the jam. The tiles would jump around, animations wouldn’t trigger, and I couldn’t figure out why. This is where Claude Code became invaluable, helping me systematically debug and solve each issue. I documented the entire debugging process in docs/tile-animation-fix.md, but here are the key challenges:

Challenge 1: CSS Transform Conflicts

Problem : The base .tile class applied a transform to position tiles at their final location:


.tile {
  transform: translate(calc(var(--tile-x) * ...));
}

When the animation class was added, the base transform took precedence, causing tiles to jump to their destination instantly.

Solution : Conditional base transform using :not() selectors:


.tile:not(.tile-moving):not(.tile-merged):not(.tile-new) {
  transform: translate(...);
}

Now animations have full control over the transform property.

Challenge 2: Animation State Persistence

Problem : When cloning the grid between moves, animation state (previousPosition, mergedFrom) was being copied, causing stale animation data.

Solution : Modified cloneGrid() to only copy core properties:


export function cloneGrid(grid: Grid): Grid {
  return grid.map(row =>
    row.map(cell =>
      cell ? {
        id: cell.id,
        value: cell.value,
        position: { ...cell.position },
        // Don't copy animation state
      } : null
    )
  );
}

Challenge 3: Animation Not Retriggering

Problem : CSS animations only start when the animation class is first added. React reuses DOM elements with the same key, so changing CSS variables alone doesn’t restart animations.

Solution : Force DOM reflow with direct manipulation:


useEffect(() => {
  if (shouldAnimate && elementRef.current) {
    const element = elementRef.current;
    element.classList.remove('tile-moving');
    void element.offsetWidth; // Force reflow
    element.classList.add('tile-moving');
  }
}, [previousPosition?.row, previousPosition?.col, shouldAnimate]);

The void element.offsetWidth forces the browser to process the class removal before re-adding it.

Challenge 4: Bubble Wobble Effect

To enhance the ocean theme, I added an idle “wobble” animation to make tiles look like floating bubbles. The trick was making them wobble at different times:


const wobbleDelay = ((position.row * 4 + position.col) * 0.2) % 3;

This position-based calculation creates a natural staggered effect where each bubble has its own wobble phase.

Input Handling: Supporting All Devices

The game supports three input methods:

Keyboard : Arrow keys and WASD (case-insensitive)
Touch : Swipe gestures with 30px minimum threshold
Mouse : Click-and-drag gestures

The swipe detection logic calculates the primary axis to determine direction:


const deltaX = Math.abs(endX - startX);
const deltaY = Math.abs(endY - startY);

if (Math.max(deltaX, deltaY) < 30) return; // Too small

if (deltaX > deltaY) {
  // Horizontal swipe
  direction = endX > startX ? 'right' : 'left';
} else {
  // Vertical swipe
  direction = endY > startY ? 'down' : 'up';
}

The Move Sequence: Timing is Everything

The game uses careful timing to coordinate both movements:


const ANIMATION_DURATION = 150; // Tile slide duration
const BUBBLE_DELAY = 100; // Extra pause before bubble shift

// Player move
setGrid(playerResult.grid);
setIsAnimating(true);

// Wait for animation + delay
setTimeout(() => {
  const cleanedGrid = clearAnimationState(playerResult.grid);
  const bubbleResult = bubbleShiftUp(cleanedGrid);

  if (bubbleResult.moved) {
    setGrid(bubbleResult.grid);

    // Wait for bubble animation
    setTimeout(() => {
      spawnNewTile();
      checkWinLose();
      setIsAnimating(false);
    }, ANIMATION_DURATION);
  }
}, ANIMATION_DURATION + BUBBLE_DELAY);

This creates a smooth sequence: player swipe → tiles slide → pause → bubbles rise → new tile spawns.

Performance Optimizations

Despite being built without a game engine, the game runs smoothly:

React.memo on the Tile component prevents unnecessary re-renders
CSS animations instead of JavaScript for 60fps performance
Passive event listeners for touch events to improve scroll performance
LocalStorage for best score persistence (with graceful error handling)

Deployment: GitHub Pages with Vite

Deploying to GitHub Pages required configuring the base path in vite.config.ts:


export default defineConfig({
  base: '/bubble-2048/',
  plugins: [react()],
});

Then build and deploy:


npm run build
# Push dist/ folder to gh-pages branch

Key Learnings

Building this game taught me several valuable lessons:

CSS animations don’t restart automatically – you need to remove and re-add classes, forcing a reflow
Simple state is better – direct prop calculations beat complex useState/useEffect coordination
Animation timing is crucial – the 250ms pause between movements makes both animations visible
Clean state between phases – clearing animation properties prevents conflicts
Game jams force focus – limited time means prioritizing core mechanics over feature creep

Future Improvements

If I continue developing this, potential additions include:

Undo functionality – storing move history for one-step-back
Daily challenges – seeded random number generation for reproducible puzzles
Leaderboards – tracking and displaying high scores
Sound effects – bubble pops, merge sounds, and ambient water audio
Progressive difficulty – larger grids or modified bubble mechanics

Try It Yourself

Play the game : https://furic.github.io/bubble-2048/
Source code : https://github.com/furic/bubble-2048

The entire codebase is MIT licensed and well-documented. Check out the animation system deep dive in the docs folder if you’re interested in the technical details.

My best score is 3332, what’s yours?

The post Building Bubble 2048: A Technical Deep Dive appeared first on Richard Fu.

Unity WebGL Background Tabs: Autoplay & Performance Fix

Richard Fu — Wed, 31 Dec 2025 06:45:13 +0000

Unity WebGL games face severe performance degradation in inactive browser tabs due to aggressive requestAnimationFrame throttling (~1 FPS). This creates race conditions and freezes when implementing autoplay features. We solved this by:

Detecting tab visibility and skipping Unity communication entirely during background autoplay
Tracking Unity’s internal state to detect and recover from desynchronization
Adding strategic delays to accommodate Unity’s “wake-up” period when tabs become active
Skipping blocking UI modals that wait for user interaction

Understanding Unity WebGL background tabs behavior is essential for any casino game, idle game, or simulation that uses autoplay features. Native web technologies (Three.js, PixiJS) don’t face these issues due to their direct JavaScript integration, making this a Unity-specific challenge.

The Problem: When Autoplay Meets Inactive Tabs

Background: Building a Game with Unity WebGL

We were building a browser-based game using Unity WebGL for its 3D rendering capabilities. The game architecture follows a hybrid model:

Unity Layer : Handles visual simulation, animations, and particle effects
Web Layer : Manages server communication, authentication, game logic, and UI

Communication between layers happens via Unity’s SendMessage API (Web → Unity) and Application.ExternalCall (Unity → Web).

The Autoplay Feature

Users requested an autoplay feature – click once, play multiple rounds automatically. Simple enough:


class GameplayManager {
  async playRound() {
    // 1. Request round result from server
    const result = await api.requestRound();

    // 2. Send result to Unity for visual simulation
    unityInstance.SendMessage('GameController', 'StartSimulation', JSON.stringify(result));

    // 3. Wait for Unity to complete animation
    await waitForUnityCallback('SimulationComplete');

    // 4. If autoplay enabled, play next round
    if (this.autoplayMode) {
      this.playRound(); // Recursive
    }
  }
}

It worked perfectly… until users switched browser tabs.

The Mystery: Everything Breaks in Background Tabs

Symptom 1: Autoplay Stops Completely

When a user enabled autoplay and switched tabs:

✅ First round completes normally
❌ Second round starts, but never finishes
❌ Game frozen when user returns to tab

Console logs revealed:


[Game] Sending simulation to Unity...
[Unity] Received simulation data
[Unity] Starting animation...
[Game] Waiting for Unity callback...
[... nothing ...]

Unity never called back. The animation never completed. Autoplay stuck forever.

Symptom 2: Seed Desynchronization

When users returned to the tab during autoplay:

❌ Unity showed the wrong level/seed
❌ Visual simulation didn’t match server results
❌ Player saw corrupted/glitched gameplay

Example:


Background: Played seed #1705 (skipped Unity)
Background: Started seed #839 (skipped Unity)
User returns: Unity still on seed #1705
Web sends: "Start simulation for seed #839"
Unity: Generates seed #839 on top of #1705's level
Result: Corrupted level geometry, wrong obstacles

Symptom 3: Success Rounds Never Complete

For rounds with positive results (score > 0):

✅ Server response received
✅ Score updated correctly
❌ Game state stuck at “showing results” instead of “idle”
❌ Next round never triggers

The logs showed:


[Game] Round completed with score: 150
[ResultsUI] Showing results modal...
[Game] Waiting for user to close modal...
[... stuck forever ...]

The results modal waited for a user click that would never come in a background tab.

Understanding the Root Cause: Browser Tab Throttling

How Browsers Throttle Inactive Tabs

Modern browsers aggressively throttle inactive tabs to save CPU and battery:

API	Active Tab	Inactive Tab
`requestAnimationFrame`	~60 FPS	~1 FPS
`setTimeout` (< 4ms)	As specified	≥1000ms
`setInterval`	As specified	≥1000ms
Network requests	Normal	✅ Normal
WebSocket	Normal	✅ Normal

Key insight: Network APIs continue working normally, but anything timing-related gets severely throttled.

Why Unity WebGL Suffers More Than Native Code

Unity WebGL’s architecture makes it particularly vulnerable:

1. Separate Runtime Sandbox


Browser JS ←→ Message Queue ←→ Unity WebAssembly Runtime
   (60 FPS) (throttled!) (~1 FPS in background)

2. Message Queue Delays


// Web sends message to Unity
unityInstance.SendMessage('GameObject', 'Method', data);
// ↓
// Message enters Unity's internal queue
// ↓
// Unity processes queue on next Update() call (every ~1000ms in background)
// ↓
// Unity executes method
// ↓
// Unity sends callback via Application.ExternalCall()
// ↓
// Callback enters browser's task queue
// ↓
// Browser processes callback on next frame (~1000ms later)

Total latency in background: ~2-3 seconds per message

3. Animation Completion Detection

Unity animations rely on frame updates:


void Update() {
    animationTimer += Time.deltaTime; // Only updates at ~1 FPS
    if (animationTimer >= duration) {
        SendCompletionCallback();
    }
}

At 1 FPS, a 3-second animation takes 3 minutes to complete.

Failed Solutions: What Didn’t Work

Attempt 1: Shorter Timeouts

Hypothesis: Maybe 100ms isn’t enough. Try longer delays.


setTimeout(() => {
  if (unityResponded) {
    continueAutoplay();
  }
}, 5000); // Wait 5 seconds instead of 100ms

Result: ❌ Still frozen. Unity simply doesn’t respond at reasonable speeds in background tabs.

Attempt 2: Promise.race with Timeout

Hypothesis: Use timeout as fallback if Unity takes too long.


await Promise.race([
  waitForUnityCallback('complete'),
  new Promise(resolve => setTimeout(resolve, 10000))
]);

Result: ❌ Timeout fires, but game state is now inconsistent. Unity still processing old simulation when we start new one.

Attempt 3: Visibility Change Detection

Hypothesis: Pause autoplay when tab becomes inactive.


document.addEventListener('visibilitychange', () => {
  if (document.hidden) {
    pauseAutoplay();
  }
});

Result: ❌ Defeats the purpose. Users want autoplay to continue in background tabs.

The Solution: Skip Unity Entirely in Background

The breakthrough realization: Unity is only needed for visual feedback. Server responses contain all game logic.

Architecture Shift

Before:


Server → Web → Unity → Web → Next Round
         ↓ ↓ ↓
      Request Render Callback

After:


Active Tab: Server → Web → Unity → Web → Next Round
Background: Server → Web → [Skip Unity] → Next Round

Implementation: Four-Layer Solution

Layer 1: Tab Visibility Detection

Skip Unity communication when tab is hidden AND autoplay is active:


protected async onRoundStart(): Promise<void> {
  const isTabHidden = document.hidden;
  const isAutoplay = getUIManager()?.autoplayMode || false;

  if (!isTabHidden || !isAutoplay) {
    // Normal flow: send to Unity for visual animation
    await unityInterface.startRound();
    this.lastUnitySeed = null; // Reset seed tracker
  } else {
    // Background autoplay: skip Unity entirely
    console.log('[Background] Skipping Unity round start');
  }
}

Apply the same pattern to all Unity communication points:

startRound() – Game initialization
startSimulation() – Simulation trigger
showResults() – Success animation
completeRound() – Cleanup

Layer 2: Seed State Tracking

Track which seed Unity currently has loaded to detect desynchronization:


export abstract class SeedGameplayManager extends BaseGameplayManager {
  private lastUnitySeed: string | number | null = null;

  protected async onSimulationStart(roundResponse: RoundResponse): Promise<void> {
    const currentSeed = roundResponse.events[0].seed;

    if (isTabHidden && isAutoplay) {
      // Background: don't update lastUnitySeed
      // This flags a mismatch when user returns
      skipUnityAndContinue();
    } else {
      // Check for mismatch from previous background play
      if (this.lastUnitySeed !== null && this.lastUnitySeed !== currentSeed) {
        console.log(`Seed mismatch: Unity=${this.lastUnitySeed}, need=${currentSeed}`);
        await unityInterface.startRound(); // Reset Unity
        await sleep(500); // Wait for Unity to wake up
      }

      unityInterface.startSimulation(stateJson);
      this.lastUnitySeed = currentSeed; // Update tracker
    }
  }
}

Why this works:

Background spins don’t update lastUnitySeed
When user returns, we detect mismatch immediately
We reset Unity before sending new seed
This prevents level corruption

Layer 3: Smart Recovery with Wake-Up Delay

When tabs become active, Unity needs time to recover from low FPS:


if (this.lastUnitySeed !== null && this.lastUnitySeed !== currentSeed) {
  // Step 1: Reset Unity
  await unityInterface.startRound();

  // Step 2: CRITICAL - Wait for Unity to wake up
  // Tab just became visible, Unity transitioning from 1 FPS → 60 FPS
  console.log('[Recovery] Waiting 500ms for Unity wake-up...');
  await new Promise(resolve => setTimeout(resolve, 500));

  // Step 3: Now Unity is ready for new commands
  unityInterface.startSimulation(stateJson);
}

Timeline:


0ms: Tab becomes visible
0ms: Send startRound() to Unity (reset command)
0-100ms: Unity at ~1-10 FPS, processing reset slowly
100-300ms: Unity FPS ramping up (10→30→60 FPS)
300-500ms: Unity stabilizes at 60 FPS, reset complete
500ms: Send startSimulation() - Unity processes immediately ✅

Without the delay:


0ms: Send startRound() - Unity queues it
0ms: Send startSimulation() - Unity queues it
100ms: Unity processes startRound() slowly
200ms: Unity tries to process startSimulation() but internal state not ready
Result: Command lost or processed incorrectly ❌

Layer 4: Skip Blocking UI

Modal dialogs that wait for user interaction block the entire async flow:


public async showResultsModal(): Promise<void> {
  if (this.latestScore === 0) return;

  // CRITICAL: Skip modal in background tabs
  // Modal waits for user click which never comes
  if (document.hidden) {
    console.log('[ResultsUI] Background - skipping modal');
    return; // Resolve immediately
  }

  // Normal flow: show modal and wait for user interaction
  return new Promise((resolve) => {
    const modal = createModal({
      content: resultsContent,
      onClose: () => resolve() // Waits for click
    });
  });
}

The async blocking chain:


// gameplayManager.ts
protected async transitionToComplete(): Promise<void> {
  if (this.lastScore > 0) {
    await Promise.all([
      this.sendEndRoundRequest(),
      this.emit('roundComplete') // ← Waits for listeners
    ]);
  }
  this.completeRound();
}

// ResultsUI.ts
eventEmitter.on('roundComplete', async () => {
  await this.showResultsModal(); // ← Blocks if waiting for click
});

Without the skip:


Background: Results modal created
Background: Promise waiting for click
Background: No user present to click
Background: Promise never resolves
Background: transitionToComplete() never completes
Background: completeRound() never called
Background: Game stuck in "showing results" state
Background: Autoplay frozen ❌

With the skip:


Background: Detect document.hidden
Background: Skip modal, return immediately
Background: transitionToComplete() completes
Background: completeRound() → state = "idle"
Background: Autoplay continues ✅

Results: Smooth Background Autoplay

Performance Metrics

Before fixes:

Background autoplay: ❌ Frozen after 1 round
Tab switch recovery: ❌ Corrupted visuals
Success animation completion: ❌ Stuck forever

After fixes:

Background autoplay: ✅ Continuous at server speed (~300ms/round)
Tab switch recovery: ✅ Automatic reset + sync (~500ms)
Success animation completion: ✅ Instant in background

Flow Comparison

Scenario: User enables autoplay, switches tabs for 30 seconds

Before:


0s: Round 1 starts, completes (Unity active)
3s: Round 2 starts
3.1s: User switches tab
3.1s: Unity receives simulation command (queued)
5s: Unity still processing at 1 FPS
10s: Unity still processing at 1 FPS
30s: User returns - game frozen on Round 2

After:


0s: Round 1 starts, completes (Unity active)
3s: Round 2 starts
3.1s: User switches tab
3.1s: Detect hidden tab → skip Unity
3.4s: Round 2 completes (server-side only)
3.7s: Round 3 starts → skip Unity
4.0s: Round 3 completes
... 25 more rounds in 30 seconds ...
30s: User returns - seed mismatch detected
30s: Reset Unity + 500ms delay
30.5s: Round 28 plays with correct visuals ✅

Why Three.js and PixiJS Don’t Have This Problem

The issues we faced are Unity WebGL-specific. Native web rendering libraries handle background tabs gracefully.

Architecture Comparison

Aspect	Unity WebGL	Three.js / PixiJS
Runtime	Separate WebAssembly sandbox	Native JavaScript
Communication	Message queue (async, throttled)	Direct function calls (instant)
Main Loop	Unity’s Update() via RAF	Your render loop via RAF
State Management	Isolated in Unity C# code	Shared JavaScript context
Background Impact	Complete freeze (~1 FPS)	Rendering paused, logic continues

Three.js Example

With Three.js, background autoplay is trivial:


class ThreeJSGame {
  async playRound() {
    // 1. Server request - works normally in background
    const result = await api.requestRound();

    // 2. Update game state - pure JavaScript, instant
    this.updateGameLogic(result);

    // 3. Conditionally render visuals
    if (!document.hidden) {
      await this.animateScene(result); // Skip in background
    }

    // 4. Complete round - instant
    this.onRoundComplete();

    // 5. Continue autoplay - no blocking!
    if (this.autoplayMode) {
      this.playRound();
    }
  }

  private async animateScene(result: GameResult) {
    // Three.js rendering - skipped when document.hidden
    return new Promise(resolve => {
      const animate = () => {
        if (this.animationComplete) {
          resolve();
          return;
        }

        // Update camera, objects, etc.
        this.camera.position.lerp(targetPos, 0.1);
        this.mesh.rotation.y += 0.01;

        // Render frame
        this.renderer.render(this.scene, this.camera);

        requestAnimationFrame(animate);
      };
      animate();
    });
  }
}

No need for:

❌ Message queue synchronization
❌ Seed state tracking
❌ Wake-up delays
❌ Manual desync detection

Just:

✅ Skip rendering loop if document.hidden
✅ Continue game logic at full speed
✅ Everything stays synchronized automatically

PixiJS Example

PixiJS follows the same pattern:


class PixiGame {
  private animationLoop(): void {
    // Game logic - always runs
    this.updatePhysics(deltaTime);
    this.checkCollisions();
    this.updateScore();

    // Rendering - conditional
    if (!document.hidden) {
      this.renderer.render(this.stage);
    }

    requestAnimationFrame(() => this.animationLoop());
  }

  async playRound() {
    const result = await api.requestRound();

    // Update sprites, positions, etc. - instant
    this.updateGameObjects(result);

    // Wait for animation if visible
    if (!document.hidden) {
      await this.waitForAnimation(3000);
    }

    // Continue - no blocking
    if (this.autoplayMode) this.playRound();
  }
}

Key Differences Explained

1. Synchronous State Access

Unity WebGL:


// Must send message and wait for callback
unityInstance.SendMessage('GameObject', 'GetScore', '');
// ... wait for Unity to process ...
// ... wait for callback ...
const score = await waitForCallback();

Three.js/PixiJS:


// Direct access - instant
const score = this.gameState.score;

2. No Communication Overhead

Unity WebGL:


Every operation requires:
1. Serialize data to JSON
2. Send via SendMessage
3. Unity deserialize JSON
4. Unity process in Update()
5. Unity serialize response
6. Send via ExternalCall
7. Browser deserialize response

Total: ~2-3 seconds in background tab

Three.js/PixiJS:


Every operation is:
1. Direct function call

Total: <1ms

3. Shared Context

Unity WebGL:


// Two separate worlds
const webState = { round: 5, score: 100 };
const unityState = { round: 3, score: 0 }; // Out of sync!
// Must manually synchronize

Three.js/PixiJS:


// Single source of truth
class Game {
  state = { round: 5, score: 100 };

  updateLogic() { this.state.score += 10; }
  renderVisuals() { this.scoreText.text = this.state.score; }
  // Always in sync
}

4. Selective Rendering

Unity WebGL:


// Unity's Update() always tries to run everything
void Update() {
    UpdatePhysics(); // Throttled to 1 FPS
    UpdateAnimation(); // Throttled to 1 FPS
    UpdateAI(); // Throttled to 1 FPS
    Render(); // Throttled to 1 FPS
    // Can't separate logic from rendering
}

Three.js/PixiJS:


function gameLoop() {
  // Logic - always runs at full speed
  updatePhysics(deltaTime); // 60 FPS even in background
  updateAI(); // 60 FPS even in background

  // Rendering - skip in background
  if (!document.hidden) {
    renderer.render(scene); // 0 FPS in background
  }
}

When to Use Each Technology

Choose Unity WebGL When:

✅ You need a full 3D engine with physics, lighting, particles

✅ You have existing Unity assets/expertise

✅ You’re targeting multiple platforms (desktop, mobile, console, web)

✅ Visual fidelity is critical

✅ Background tab performance is not a priority

Trade-offs:

Larger bundle size (~10-50 MB)
Compilation required
Background tab challenges (as discussed)
Less direct browser API access

Choose Three.js When:

✅ You need custom 3D rendering with full control

✅ Background tab performance matters

✅ You want smaller bundle sizes

✅ You need direct browser API integration

✅ You’re comfortable with JavaScript/TypeScript

Trade-offs:

More manual setup (physics, lighting, etc.)
Steeper learning curve for 3D graphics
No visual editor

Choose PixiJS When:

✅ You’re building 2D games

✅ Performance is critical

✅ Background tab support is required

✅ You want the smallest bundle size

✅ You need maximum browser compatibility

Trade-offs:

Limited to 2D (no 3D capabilities)
Manual sprite management
No built-in physics engine

Lessons Learned

1. Browser Tab Throttling is Aggressive

Don’t assume requestAnimationFrame, setTimeout, or any timing APIs work normally in background tabs. They don’t.

2. Network APIs Are Reliable

Fetch, WebSocket, and other network APIs continue working at full speed regardless of tab visibility. Build your architecture around this.

3. Unity WebGL Needs Special Handling

Unity WebGL’s sandboxed runtime creates unique challenges. Budget extra development time for cross-context communication and state synchronization.

4. Always Have a Fallback

When integrating external runtimes (Unity, iframes, Web Workers), always implement:

Timeout detection
State synchronization
Recovery mechanisms
Graceful degradation

5. Test in Real Conditions

Background tab behavior varies by:

Browser (Chrome, Firefox, Safari)
Device (desktop, mobile, tablet)
Battery state (plugged in vs. battery)
System load (other tabs, apps)

Always test with actual tab switching, not just document.hidden = true.

Conclusion

Unity WebGL is a powerful tool for bringing 3D games to the browser, but its sandboxed architecture creates unique challenges for features that must work in background tabs. By understanding browser throttling behavior and implementing strategic workarounds—skipping Unity during background operations, tracking synchronization state, adding recovery delays, and removing blocking UI—we achieved smooth autoplay functionality that works reliably regardless of tab visibility.

For new projects, consider whether Unity’s benefits (full 3D engine, cross-platform support, visual editor) outweigh its limitations (background tab challenges, large bundle size, communication overhead). Native web technologies like Three.js and PixiJS offer simpler architectures with better background tab support, at the cost of requiring more manual setup.

The key insight: Unity is for visual feedback. Keep your game logic in JavaScript, and treat Unity as a pure rendering layer.

Resources

The post Unity WebGL Background Tabs: Autoplay & Performance Fix appeared first on Richard Fu.

Building a Web-Unity WebGL Bridge: A Practical Guide

Richard Fu — Sat, 13 Dec 2025 15:22:32 +0000

When you’re building games that need both the power of Unity’s 3D engine and the flexibility of modern web technologies, you quickly discover that making them communicate isn’t as straightforward as it seems. After building several hybrid web-Unity applications, I’ve learned quite a few lessons about what works, what doesn’t, and what will make you want to throw your keyboard out the window.

While the well-established React Unity WebGL library already does a great job, this guide walks you through building a robust communication bridge from scratch between a TypeScript/JavaScript web frontend and Unity WebGL builds. I’ll share the architecture we settled on, the mistakes we made along the way, and the solutions we found.

Why Build a Hybrid Architecture?

Before diving into the technical details, let’s address the “why.” You might be wondering: if Unity can build for WebGL, why not just use Unity for everything?

In our case, we were building multiple games that shared common functionality:

Authentication & session management – handled by our backend SDK
Internationalization – 16+ languages with dynamic switching
UI framework – consistent menus, settings panels, modals across games
Audio system – web audio API with Howler.js for UI sounds
State persistence – localStorage, session handling

Each game had unique 3D gameplay, but 80% of the surrounding infrastructure was identical. Building all of this in Unity for each game would mean:

Duplicating shared code across projects
Longer iteration cycles (Unity builds take time)
Larger bundle sizes (Unity UI is heavy)
Less flexibility in web-specific features

Our solution: a shared web engine that handles the “chrome” around the game, while Unity handles the 3D gameplay. The web layer sends commands to Unity (“start the game”, “play this seed”), and Unity sends results back (“game complete”, “animation finished”).

The Architecture at a Glance

Here’s the high-level flow:

Web (TypeScript) Unity WebGL
----------------- -----------
GameplayManager GameController.cs
      | ^
      v |
UnityInterface -------SendMessage-------> WebInterface.cs
      | |
      | <------ExternalCall-------- |
      v v
   GameUI Game Scene

The communication is bidirectional:

Web to Unity : Uses Unity’s SendMessage() API
Unity to Web : Uses Application.ExternalCall() (or the modern jslib approach)

Messages are JSON strings in both directions, giving us type safety and flexibility.

The Key Mistakes We Made (So You Don’t Have To)

Mistake #1: Inconsistent GameObject Naming

Unity’s SendMessage() API requires you to specify a GameObject name:

unityInstance.SendMessage('WebInterface', 'StartGame', data);

Sounds simple, right? Here’s where we messed up: different developers named the receiving GameObject differently across projects. One called it “WebInterface”, another “WebBridge”, another “GameManager”.

When we tried to create a reusable engine, nothing worked because each game expected a different name.

Solution: Establish a strict naming convention and stick to it. We settled on pattern-based names:

– WebSeedInterfaces – for seed-based games

– WebRoundInterfaces – for round-based games

– WebSettingsInterface – for audio/language/settings

The “Interfaces” suffix (plural) reminds us it’s a collection of interface methods, not a single one.

Mistake #2: Complex JSON Message Structures

Our first implementation sent messages like this:

// Web side - sending
unityInstance.SendMessage('WebInterface', 'ReceiveMessage', JSON.stringify({
    action: 'setDifficulty',
    data: {
        difficulty: 'hard',
        timestamp: Date.now()
    }
}));

// Unity side - receiving
public void ReceiveMessage(string json) {
    var msg = JsonUtility.FromJson<WebMessage>(json);
    switch(msg.action) {
        case "setDifficulty":
            var data = JsonUtility.FromJson<DifficultyData>(msg.data);
            SetDifficulty(data.difficulty);
            break;
        // ... 20 more cases
    }
}

This meant:

– Unity needed to parse JSON twice (outer message + inner data)

– Giant switch statements that grew with every feature

– Type definitions on both sides had to stay in sync

– Debugging was painful

Solution: Use direct method calls with simple values. Unity’s SendMessage() can call any public method directly:

// Web side - much simpler!
unityInstance.SendMessage('WebRoundInterfaces', 'WebSetDifficulty', 'hard');
unityInstance.SendMessage('WebRoundInterfaces', 'WebStartRound', '');
unityInstance.SendMessage('WebSettingsInterface', 'WebSetLanguage', 'en'); 

// Unity side - clean methods
public void WebSetDifficulty(string difficulty) {
    _difficulty = difficulty;
    OnDifficultyChanged?.Invoke(difficulty);
}

public void WebStartRound(string _unused) {
    StartRound();
}

public void WebSetLanguage(string languageCode) {
    SetLanguage(languageCode);
}

We adopted a Web[Verb][Noun] naming pattern for all web-callable methods. This makes it immediately clear which methods are called from the web side.

Mistake #3: Not Handling the “Unity Not Ready” State

Unity WebGL takes time to load. If your web code tries to send messages before Unity is ready, they simply disappear into the void.

Our first “fix” was to add arbitrary delays:

// Don't do this
setTimeout(() => {
    unityInstance.SendMessage('WebInterface', 'Initialize', '');
}, 3000); // Hope 3 seconds is enough...

Spoiler: it wasn’t always enough. And sometimes it was too much.

Solution: Implement a message queue that holds messages until Unity signals it’s ready:

class UnityManager {
    private messageQueue: Array<{methodName: string; value?: any}> = [];
    private connectionState: 'disconnected' | 'loading' | 'ready' = 'disconnected';

    async sendMessage(methodName: string, value?: any): Promise<void> {
        if (this.connectionState !== 'ready') {
            // Queue message for later
            this.messageQueue.push({ methodName, value });
            return;
        }
        await this.sendMessageToUnity(methodName, value);
    }

    // Called when Unity sends 'gameReady' message
    private onUnityReady(): void {
        this.connectionState = 'ready';
        // Process queued messages
        this.processMessageQueue();
    }

    private async processMessageQueue(): Promise<void> {
        while (this.messageQueue.length > 0) {
            const message = this.messageQueue.shift();
            await this.sendMessageToUnity(message.methodName, message.value);
        }
    }
}

On the Unity side, send a “ready” signal when the game is initialized:

void Start() {
    // Send ready signal to web
    SendToWeb("gameReady", null);
}

public void SendToWeb(string action, object data) {
    var message = JsonUtility.ToJson(new { action, data });
    Application.ExternalCall("UnityMessageHandler", message);
}

Mistake #4: Forgetting That SendMessage Only Takes Strings

This one bit us multiple times. Unity’s SendMessage() can only pass string, int, or float parameters. No objects, no booleans, no arrays.

// This silently fails or behaves unexpectedly
unityInstance.SendMessage('WebInterface', 'SetEnabled', true);
unityInstance.SendMessage('WebInterface', 'SetConfig', { foo: 'bar' });

Solution: Always convert to strings on the web side, parse on the Unity side:

// Web side
private async sendMessageToUnity(methodName: string, value?: any): Promise<void> {
    // Convert value to string - Unity SendMessage always expects string
    const messageData = value !== undefined ? String(value) : '';
    this.unityInstance.SendMessage(this.gameObjectName, methodName, messageData);
}

// Unity side - parse boolean from string
public void WebSetTurbo(string boolValue) {
    bool enabled = bool.Parse(boolValue); // "true" -> true
    SetTurboMode(enabled);
}

// Unity side - parse number from string
public void WebSetRound(string roundNumber) {
    int round = int.Parse(roundNumber); // "5" -> 5
    SetRound(round);
}

Unity Build Settings That Matter

Your Unity WebGL build settings significantly impact how well the bridge works. Here’s what we learned:

Player Settings

Edit > Project Settings > Player > WebGL Settings

Product Name: Game // Use a generic name for reusability
Compression Format: Gzip // Best balance of size and compatibility
Decompression Fallback: Yes // For older browsers
Run In Background: Yes // Keep running when tab loses focus

The Product Name becomes part of your build filenames (Game.wasm, Game.framework.js, etc.). Using a generic name like “Game” means your web engine doesn’t need per-game configuration.

Build Configuration

File > Build Settings > WebGL

Development Build: [checked for dev, unchecked for prod]
Code Optimization: Speed (for production)
Enable Exceptions: Explicitly Thrown Only
Strip Engine Code: Yes (reduces file size)

Vite Configuration for Unity WebGL

If you’re using Vite (or similar bundler), you need specific configuration to handle Unity files:

// vite.config.ts
export default defineConfig({
    server: {
        headers: {
            // Required for Unity WebGL SharedArrayBuffer support
            'Cross-Origin-Embedder-Policy': 'require-corp',
            'Cross-Origin-Opener-Policy': 'same-origin'
        }
    },
    build: {
        assetsInlineLimit: 0, // Don't inline Unity assets
        chunkSizeWarningLimit: 10000, // Unity files can be large
        rollupOptions: {
            output: {
                assetFileNames: (assetInfo) => {
                    // Keep Unity files with their original names
                    if (assetInfo.name?.endsWith('.data') ||
                        assetInfo.name?.endsWith('.wasm') ||
                        assetInfo.name?.endsWith('.framework.js')) {
                        return '[name][extname]';
                    }
                    return 'assets/[name]-[hash][extname]';
                }
            }
        }
    }
});

Silencing Unity’s Console Noise

Unity WebGL builds are chatty. Like, really chatty. Open your browser console and you’ll see hundreds of messages about memory allocation, WebGL state, physics initialization, and more.

This isn’t just annoying – it can hide actual errors and slow down the browser’s developer tools.

The Console Filter Approach

We intercept console methods before Unity loads and filter out the noise:

<!-- index.html - MUST be before any Unity scripts -->
<script>
(function() {
    // Store original console methods
    const originalConsole = {
        log: console.log.bind(console),
        warn: console.warn.bind(console),
        error: console.error.bind(console)
    };

    // Detect build mode (replaced by build tool)
    const isProduction = __VITE_BUILD_MODE__ ;

    // Unity internal patterns to suppress
    const unityPatterns = [
        /\[UnityMemory\]/, /\[Physics::Module\]/, /memorysetup-/,
        /Loading player data/, /Initialize engine version/, /Creating WebGL/,
        /^Renderer:/, /^Vendor:/, /^GLES:/, /OPENGL LOG:/,
        /UnloadTime:/, /JS_FileSystem_Sync/, /Configuration Parameters/,
        /\$func\d+ @ Game\.wasm/, /Module\._main @ Game\.framework\.js/
    ];

    // Custom Debug.Log patterns to KEEP (your game's logs)
    const customPatterns = [
        /\[WebRoundInterface\]/, /\[GameplayController\]/,
        /\[[A-Z][A-Za-z]*(?:Interface|Controller|Manager)\]/
    ];

    function shouldSuppress(message) {
        // Production: suppress everything
        if (isProduction) return true;

        // Development: suppress Unity internal, keep custom
        const isUnityInternal = unityPatterns.some(p => p.test(message));
        if (isUnityInternal) {
            const isCustomLog = customPatterns.some(p => p.test(message));
            return !isCustomLog;
        }
        return false;
    }

    // Override console methods
    ['log', 'warn', 'error'].forEach(level => {
        console[level] = function(...args) {
            const message = args.map(String).join(' ');
            if (!shouldSuppress(message)) {
                originalConsole[level](...args);
            }
        };
    });

    // Store original for emergency access
    window.__originalConsole = originalConsole;
})();
</script>

Suppressing WebGL Warnings at the Source

Some WebGL warnings happen during API calls, before any console filtering can catch them. Unity queries texture formats that may not be supported, and Chrome helpfully logs WebGL: INVALID_ENUM warnings.

The nuclear option: patch the WebGL API itself:

if (typeof WebGL2RenderingContext !== 'undefined') {
    const original = WebGL2RenderingContext.prototype.getInternalformatParameter;

    // Known invalid formats Unity queries
    const invalidFormats = new Set([
        36756, 36757, 36759, 36760, 36761, 36763 // Compressed texture formats
    ]);

    WebGL2RenderingContext.prototype.getInternalformatParameter = function(
        target, internalformat, pname
    ) {
        // Block Unity's known invalid queries before they trigger warnings
        if (invalidFormats.has(internalformat)) {
            return null;
        }
        return original.call(this, target, internalformat, pname);
    };
}

Post-Build Processing

For production builds, we also modify Unity’s generated files:

// post-unity-build.js - Run after Unity build
import fs from 'fs';

const frameworkFile = './public/unity/Build/Game.framework.js';
const loaderFile = './public/unity/Build/Game.loader.js';

// Read Unity framework file
let framework = fs.readFileSync(frameworkFile, 'utf8');

// Prepend WebGL fix
const webglFix = `
(function () {
    const original = WebGL2RenderingContext.prototype.getInternalformatParameter;
    const invalid = new Set([36756, 36757, 36759, 36760, 36761, 36763]);
    WebGL2RenderingContext.prototype.getInternalformatParameter = function(t, i, p) {
        if (invalid.has(i)) return null;
        return original.call(this, t, i, p);
    };
})();
`;

// Replace console.log/warn with void 0
framework = webglFix + framework.replace(/(\W)console\.(log|warn)\([^)]*\);/g, '$1void 0;');

fs.writeFileSync(frameworkFile, framework);

// Suppress Unity Analytics in loader
let loader = fs.readFileSync(loaderFile, 'utf8');

const analyticsFix = `
(function() {
    const originalFetch = window.fetch;
    window.fetch = function(...args) {
        if (typeof args[0] === 'string' && args[0].includes('unity3d.com')) {
            return Promise.reject(new Error('Analytics disabled'));
        }
        return originalFetch.apply(this, args);
    };
})();
`;

loader = analyticsFix + loader.replace(/console\.(log|warn)\([^)]*\)/g, 'void 0');
fs.writeFileSync(loaderFile, loader);

console.log('Unity build post-processed successfully');

The Final Architecture

After all these iterations, here’s what our architecture looks like:

Web Side (TypeScript)

// UnityManager - Low-level communication
class UnityManager {
    private messageQueue: Message[] = [];
    private connectionState: ConnectionState = 'disconnected';

    async initialize(config: UnityConfig): Promise<void> { /* ... */ }
    async loadUnityGame(canvas?: HTMLCanvasElement): Promise<void> { /* ... */ }
    async sendMessage(methodName: string, value?: any): Promise<void> { /* ... */ }
}

// Domain-specific interfaces
class UnitySeedInterface {
    async startSpin(): Promise<void> { /* WebStartSpin */ }
    async startRevealing(seed: string): Promise<void> { /* WebStartRevealing */ }
    async startPayout(amount: string): Promise<void> { /* WebStartPayout */ }
    async completeSpin(): Promise<void> { /* WebCompleteSpin */ }
}

class UnitySettingsInterface {
    async setSound(enabled: boolean): Promise<void> { /* WebToggleSound */ }
    async setLanguage(lang: string): Promise<void> { /* WebSetLanguage */ }
    async setTurbo(enabled: boolean): Promise<void> { /* WebSetTurbo */ }
}

Unity Side (C#)

public class WebSeedInterface : MonoBehaviour
{
    public UnityEvent OnSpinStarted;
    public UnityEvent<string> OnRevealing;
    public UnityEvent<string> OnPayout;
    public UnityEvent OnSpinCompleted;

    void Start() => SendToWeb("gameReady", null);

    public void WebStartSpin(string _) => OnSpinStarted?.Invoke();
    public void WebStartRevealing(string seed) => OnRevealing?.Invoke(seed);
    public void WebStartPayout(string amount) => OnPayout?.Invoke(amount);
    public void WebCompleteSpin(string _) => OnSpinCompleted?.Invoke();

    public void SendToWeb(string action, object data) {
        var json = JsonUtility.ToJson(new { action, data });
        Application.ExternalCall("UnityMessageHandler", json);
    }
}

// WebSettingsInterface.cs - Audio, language, turbo
public class WebSettingsInterface : MonoBehaviour
{
    public static event Action<bool> OnSoundToggled;
    public static event Action<string> OnLanguageChanged;
    public static event Action<bool> OnTurboModeToggled;

    public void WebToggleSound(string val) => OnSoundToggled?.Invoke(bool.Parse(val));
    public void WebSetLanguage(string lang) => OnLanguageChanged?.Invoke(lang);
    public void WebSetTurbo(string val) => OnTurboModeToggled?.Invoke(bool.Parse(val));
}

Key Takeaways

Standardize GameObject names – Pick a naming convention and enforce it across all projects.
Use direct method calls – Skip the JSON wrapper for simple values. WebSetDifficulty('hard') beats ReceiveMessage('{"action":"setDifficulty","data":"hard"}')
Queue messages until ready – Never assume Unity is loaded. Always queue messages and process them when Unity signals readiness.
Everything is a string – Remember that SendMessage() can only pass strings. Convert on web, parse on Unity.
Filter console noise early – Set up console filtering before Unity loads, and patch WebGL APIs if necessary.
Post-process Unity builds – Remove console calls and Unity analytics from production builds.

Building a web-Unity bridge isn’t rocket science, but the devil is in the details. These patterns have served us well across multiple games, and I hope they save you some of the headaches we experienced along the way.

Have questions or improvements? Feel free to reach out. Happy coding!

The post Building a Web-Unity WebGL Bridge: A Practical Guide appeared first on Richard Fu.

Introducing Blocky UI Lite: A 3D Blocky-Themed Component Library 🎮

Richard Fu — Sat, 18 Oct 2025 10:20:09 +0000

Ever wanted to give your web apps that distinctive game aesthetic? Meet Blocky UI Lite – a lightweight TypeScript component library that brings 3D blocky styling to your projects with zero dependencies and pure CSS magic.

Blocky UI components with 3D depth effects

✨ What Makes It Special?

Pure CSS 3D Effects

No SVG generation, no JavaScript-based styling, no runtime overhead. Every 3D effect is achieved through carefully crafted CSS:


/* Multi-layer box shadows create depth */
box-shadow:
    0 4px 0 rgba(0, 0, 0, 0.3), /* Base shadow */
    0 8px 16px rgba(0, 0, 0, 0.4), /* Far shadow */
    inset 0 2px 0 rgba(255, 255, 255, 0.2), /* Top highlight */
    inset 0 -2px 0 rgba(0, 0, 0, 0.3); /* Bottom shadow */

/* Gradient backgrounds with transparency */
background: linear-gradient(
    180deg,
    rgba(85, 223, 255, 0.95) 0%,
    rgba(85, 223, 255, 0.7) 50%,
    rgba(85, 223, 255, 0.5) 100%
);

/* Radial overlay for extra depth */
&::before {
    background: radial-gradient(
        circle at center,
        rgba(255, 255, 255, 0.2) 0%,
        transparent 70%
    );
}

Zero Dependencies

The entire library weighs in at just ~15KB gzipped with absolutely zero runtime dependencies. It’s pure TypeScript + CSS, making it incredibly portable and performant.

Full TypeScript Support

Every component comes with complete type definitions, making development a breeze with full autocomplete and type checking:


import { BlockyUI, ComponentVariant } from 'blocky-ui-lite';

// TypeScript knows all available options
const button = BlockyUI.createButton({
    text: 'Click Me',
    variant: 'primary', // 'default' | 'primary' | 'secondary' | 'danger'
    onClick: () => console.log('Clicked!'),
    disabled: false
});

🎨 Component Variants System

One of the newest features is the unified variant system. Buttons, Cards, and Tags all support the same four color variants:

default – Neutral gray for standard elements
primary – Vibrant blue for primary actions
secondary – Bright cyan for secondary actions
danger – Bold red for destructive actions

All components support consistent color variants

🚀 Quick Start Example

Getting started is incredibly simple. Here’s a complete example creating an interactive game UI:


<!DOCTYPE html>
<html lang="en">
<head>
    <!-- CSS -->
    <link rel="stylesheet" href="https://unpkg.com/blocky-ui-lite@latest/dist/blocky-ui.css">
</head>
<body>
    <div id="game-ui"></div>

    <!-- JavaScript -->
    <script src="https://unpkg.com/blocky-ui-lite@latest/dist/index.umd.js"></script>
    <script>
        const { BlockyUI } = window.BlockyUILite;

        // Create a game stats card
        const statsCard = BlockyUI.createCard({
            title: 'Player Stats',
            variant: 'primary',
            content: `
                <p><strong>Level:</strong> 42</p>
                <p><strong>Score:</strong> 9,850</p>
                <p><strong>Coins:</strong> 1,234</p>
            `
        });

        // Create multiplier tags
        const multiplierTag = BlockyUI.createTag({
            content: '×5.0',
            variant: 'secondary'
        });

        // Create action buttons
        const playButton = BlockyUI.createButton({
            text: 'PLAY NOW',
            variant: 'primary',
            onClick: () => {
                BlockyUI.showNotification(
                    'Game Started!',
                    'Good luck and have fun!'
                );
            }
        });

        // Add to page
        const container = document.getElementById('game-ui');
        container.appendChild(statsCard);
        container.appendChild(playButton);
    </script>
</body>
</html>

🏗️ Technical Deep Dive

Component Architecture

Each component follows a consistent static factory pattern that returns instances with methods:


// Factory method creates instance
const modal = BlockyUI.createModal({
    title: 'Confirm Action',
    content: 'Are you sure?',
    buttons: [
        { text: 'Cancel', variant: 'default', onClick: () => {} },
        { text: 'Confirm', variant: 'primary', onClick: () => {} }
    ]
});

// Instance methods for control
modal.show(); // Display the modal
modal.close(); // Close programmatically

// Or use convenience methods (auto-shown)
BlockyUI.showNotification('Success!', 'Operation completed.');
BlockyUI.showError('Error!', 'Something went wrong.');
BlockyUI.showConfirmation('Delete?', 'This cannot be undone.', onConfirm, onCancel);

CSS Architecture

The library uses CSS custom properties for easy theming and consistency:


:root {
    /* Colors */
    --blocky-primary: #55dfff;
    --blocky-danger: #ff4444;

    /* 3D Effects */
    --blocky-shadow-base: 0 4px 0 rgba(0, 0, 0, 0.3);
    --blocky-shadow-far: 0 8px 16px rgba(0, 0, 0, 0.4);

    /* Spacing */
    --blocky-padding-md: 12px;
    --blocky-border-radius: 6px;

    /* Z-Index Layers */
    --blocky-z-content: 10;
    --blocky-z-dropdown: 100;
    --blocky-z-overlay-modal: 900;
}

Build Pipeline

Blocky UI uses Rollup to generate multiple module formats:

ESM (index.esm.js) – For modern bundlers (Vite, Webpack, etc.)
CJS (index.cjs.js) – For Node.js environments
UMD (index.umd.js) – For direct browser usage via CDN
TypeScript (index.d.ts) – Full type definitions

📦 Available Components

BlockyButton

Interactive buttons with 4 color variants and 3D hover effects. Perfect for CTAs and game actions.


const button = BlockyUI.createButton({
    text: 'START GAME',
    variant: 'primary',
    onClick: () => startGame(),
    disabled: false
});

BlockyModal

Overlay dialogs with backdrop blur and smooth animations. Returns an instance for manual control.


const modal = BlockyUI.createModal({
    title: 'Game Over',
    content: 'You scored 1,234 points!',
    showCloseButton: true,
    buttons: [
        { text: 'Play Again', variant: 'primary', onClick: restart }
    ]
});

modal.show(); // Display when ready

BlockyCard

Content containers with 3D styling and optional headers. Now with variant support!


const card = BlockyUI.createCard({
    title: 'Daily Rewards',
    variant: 'secondary',
    content: 'Come back tomorrow for more coins!'
});

BlockyTag

Compact labels perfect for multipliers and status indicators.


const tag = BlockyUI.createTag({
    content: '×2.5',
    variant: 'danger' // Red for high multipliers!
});

BlockyInfo

Temporary notifications with auto-dismiss and 5 color themes.


const info = BlockyUI.createInfo({
    title: 'Achievement Unlocked!',
    titleColor: 'yellow',
    content: 'You reached level 10!'
});

document.body.appendChild(info);

BlockyPage

Full-screen scrollable overlays with animated gradient borders.


const page = BlockyUI.createPage({
    content: `
        <h1>Game Rules</h1>
        <p>Here are the complete game instructions...</p>
    `,
    onClose: () => console.log('Rules closed')
});

page.show();

🎮 Real-World Use Cases

Casino Game Interfaces

Perfect for slots, roulette, poker interfaces – anywhere you need that “blocky casino” aesthetic.

Gaming Dashboards

Player stats, leaderboards, achievement systems, inventory screens.

Interactive Web Apps

Any application that wants to stand out with a unique, game-inspired design language.

Educational Platforms

Gamified learning interfaces, quiz applications, progress tracking systems.

🔧 Installation & Setup

Via npm/yarn/pnpm


# npm
npm install blocky-ui-lite

# yarn
yarn add blocky-ui-lite

# pnpm
pnpm add blocky-ui-lite



// Import CSS (required)
import 'blocky-ui-lite/styles';

// Import components
import { BlockyUI } from 'blocky-ui-lite';

// Use in your app
const button = BlockyUI.createButton({
    text: 'Click Me',
    variant: 'primary'
});

Via CDN (No Build Step)


<!-- CSS -->
<link rel="stylesheet" href="https://unpkg.com/blocky-ui-lite@latest/dist/blocky-ui.css">

<!-- JavaScript (UMD) -->
<script src="https://unpkg.com/blocky-ui-lite@latest/dist/index.umd.js"></script>

<script>
    const { BlockyUI } = window.BlockyUILite;
    // Use BlockyUI here
</script>

🎨 Framework Integration

React


import { useEffect, useRef } from 'react';
import { BlockyUI } from 'blocky-ui-lite';
import 'blocky-ui-lite/styles';

function GameButton() {
    const containerRef = useRef<HTMLDivElement>(null);

    useEffect(() => {
        if (containerRef.current) {
            const button = BlockyUI.createButton({
                text: 'PLAY',
                variant: 'primary',
                onClick: () => console.log('Game started!')
            });
            containerRef.current.appendChild(button);
        }
    }, []);

    return <div ref={containerRef} />;
}

Vue 3


<script setup lang="ts">
import { onMounted, ref } from 'vue';
import { BlockyUI } from 'blocky-ui-lite';
import 'blocky-ui-lite/styles';

const containerRef = ref<HTMLDivElement | null>(null);

onMounted(() => {
    if (containerRef.value) {
        const button = BlockyUI.createButton({
            text: 'PLAY',
            variant: 'primary',
            onClick: () => console.log('Game started!')
        });
        containerRef.value.appendChild(button);
    }
});
</script>

<template>
    <div ref="containerRef"></div>
</template>

Svelte


<script lang="ts">
    import { onMount } from 'svelte';
    import { BlockyUI } from 'blocky-ui-lite';
    import 'blocky-ui-lite/styles';

    let container: HTMLDivElement;

    onMount(() => {
        const button = BlockyUI.createButton({
            text: 'PLAY',
            variant: 'primary',
            onClick: () => console.log('Game started!')
        });
        container.appendChild(button);
    });
</script>

<div bind:this={container}></div>

🚀 Performance Considerations

Bundle Size

CSS : ~8KB minified, ~2KB gzipped
JavaScript : ~12KB minified, ~4KB gzipped
Total : ~20KB minified, ~6KB gzipped

Runtime Performance

All animations are CSS-based using transform and opacity, ensuring smooth 60fps animations with GPU acceleration. No JavaScript animation loops means zero CPU overhead.

Load Time Optimization

When using via CDN, both unpkg.com and jsdelivr.net offer automatic minification, compression, and edge caching for blazing-fast delivery worldwide.

🔮 Future Roadmap

⏳ More Components : Tabs, Tooltips, Dropdowns, Sliders
⏳ Theming API : Runtime theme switching
⏳ Animation Library : Pre-built entrance/exit animations
⏳ Form Components : Inputs, Checkboxes, Radio buttons with 3D styling
⏳ Icon System : Optional built-in icon support
⏳ Enhanced Accessibility : ARIA labels, keyboard navigation improvements

📚 Resources

🌐 Live Demo : https://furic.github.io/blocky-ui/
📦 npm Package : blocky-ui-lite
🐙 GitHub : fuR-Gaming/blocky-ui
📖 Documentation Wiki : GitHub Wiki

🤝 Contributing

Blocky UI Lite is open source and welcomes contributions! Whether it’s bug reports, feature requests, or pull requests – all contributions are appreciated.

# Clone the repository
git clone https://github.com/fuR-Gaming/blocky-ui.git

# Install dependencies
npm install

# Start development server
npm run dev

# Build the library
npm run build

📄 License

MIT License – Free to use in personal and commercial projects. No attribution required (but always appreciated! 🙏)

🎉 Conclusion

Blocky UI Lite brings a unique aesthetic to web development – one that’s perfect for gaming interfaces, casino applications, and any project that wants to stand out with bold, 3D styling. With zero dependencies, full TypeScript support, and pure CSS effects, it’s both powerful and lightweight.

Give it a try in your next project, and let us know what you build with it!

Built with ❤️ by fuR Gaming | Powered by Claude Code 🤖

The post Introducing Blocky UI Lite: A 3D Blocky-Themed Component Library 🎮 appeared first on Richard Fu.