DEV Community: 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.

Richfolio, three months in: AI architecture in production

Richard Fu — Fri, 22 May 2026 10:14:46 +0000

From v1.0 to v1.6 — what I rebuilt, what I borrowed, and what’s running in production for $0/month

Three months ago I shipped v1.0 of Richfolio — a zero-maintenance side project that emails me a daily AI-powered portfolio digest. I wrote about the original motivation and v1 architecture in this earlier post if you want the background.

Since then it’s gone through six minor releases. The code roughly tripled in size, the AI architecture got rebuilt from the ground up to handle production use, and I’ve been using it on my own portfolio daily. This post is a project-level update: where Richfolio is, what stack it runs on, the architectural patterns I borrowed (mostly from OpenAlice), and one concrete case study showing how those patterns paid off in v1.6.

At the end I’m looking for alpha testers, so if any of this is interesting and you’ve got a portfolio that doesn’t look like mine, keep reading.

What Richfolio is now

A single Node.js + TypeScript pipeline, no API server, no dashboard. Runs as a GitHub Actions cron job (8am AEST). Four modes:

Daily — full analysis + email + Telegram
Intraday — periodic STRONG BUY change alerts (only fires on real signal changes)
Weekly — rebalancing drift report
Refresh — re-analyze a single ticker with after-hours prices

Output looks like this: a dark-themed HTML email per morning, condensed Telegram message in parallel, and for every STRONG BUY ticker, a “More Details” link to a dedicated analysis page on GitHub Pages with an interactive TradingView chart, AI-generated buy thesis, and risk analysis.

The stack — still $0/month

Everything Richfolio runs on is free-tier:

Component	Service	Free tier
Prices, fundamentals, technicals	Yahoo Finance via `yahoo-finance2` v3	unlimited
News	NewsAPI.org	100 req/day
AI analysis	Google Gemini 2.5 Flash	250 req/day
Email delivery	Resend.com	3,000/month
Push notification	Telegram Bot API	unlimited
Scheduler	GitHub Actions cron	2,000 min/month
Static hosting	GitHub Pages	unlimited
State persistence	`actions/cache`	unlimited

No database. No queue. No server. State is a JSON file in the repo that survives cron runs via actions/cache. The full cost ceiling for a single user is the Resend tier — and Richfolio sends maybe 60 emails a month, so there’s headroom for ~50 users on a single account.

The interesting constraint isn’t the budget — it’s the request budget. Gemini’s 250/day cap means every “let me ask the AI” feature has to be designed around batch calls, not per-ticker calls. That shaped a lot of the architecture below.

Architecture: patterns I borrowed from OpenAlice

The biggest single influence on Richfolio’s post-v1 evolution was OpenAlice — an autonomous AI trading agent from TraderAlice. OpenAlice is much bigger than Richfolio (multi-broker, multi-asset, with a UI) but its cognitive architecture transferred cleanly. Four patterns in particular.

1. Two-stage Think/Plan AI prompting

The v1 pipeline used a single Gemini call: shove everything into one prompt, parse one JSON response. The problem: when the AI conflates data parsing with decision-making, it hallucinates support for whatever conclusion it’s already started writing. STRONG BUY false positives crept in monthly.

The fix was to split the call into two stages, mirroring OpenAlice’s think and plan tools:

Stage 1 (Observe) — Gemini gets raw data and produces structured observations only: which price-level signals are present, which momentum signals, which risk flags, a one-line valuation summary, a one-line technical summary, news sentiment. No actions, no recommendations.
Stage 2 (Decide) — Gemini gets the observations and applies strict decision rules to produce ranked recommendations.

Two API calls instead of one — wasteful in theory, but still 2/250 of the daily quota. The practical win is significant: forcing the AI to commit to what it sees before deciding what to do dropped false-positive STRONG BUYs to near zero.

2. Post-AI guard pipeline

The other half of trustworthy AI output is not trusting the AI. OpenAlice’s guard-pipeline.ts runs sequential validation between the AI’s proposed trades and the broker. Richfolio adapts the same pattern in guards.ts:


export function validateRecommendations(
  recs: AIBuyRecommendation[],
  priceData: Record<string, QuoteData>,
  technicals: Record<string, TechnicalData>,
  report: AllocationReport,
): void {
  guardBondETFCap(recs, report);
  guardEarningsProximity(recs, priceData);
  guardStrongBuyCriteria(recs, report, technicals);
  guardMaxStrongBuy(recs);
  guardConfidenceSanity(recs);
  guardBuyValueSanity(recs, report);
}

Six sequential checks that programmatically enforce the rules I told the AI to follow. Each guard logs when it fires, so I can see which AI mistakes were caught downstream — useful signal when tuning prompts.

The architectural pattern — let the AI propose freely, validate deterministically afterward — is the single most useful idea I borrowed from OpenAlice. It makes prompt experiments low-risk.

3. Seven-day reasoning persistence

OpenAlice has a Brain module that tracks cognitive state across sessions via Git-like commits. Richfolio doesn’t need that level of machinery, but the principle — let the AI see its own past conclusions — adapts cleanly to a 7-day rolling history of AI snapshots.

Every decision prompt now receives a “HISTORICAL CONTEXT” block like:


AAPL: BUY 72% → BUY 68% → HOLD 55% — weakening
NVDA: STRONG BUY 88% → STRONG BUY 91% → STRONG BUY 89% — stable
BSV: BUY 75% → BUY 75% → BUY 75% — flat

(More on that last line in a minute.)

The history forces the AI to acknowledge trend changes. Without it, the model would sometimes flip a ticker from BUY 70% to HOLD 50% on consecutive days with no acknowledgement — which feels wrong even if individually justified.

4. Macro environment context

Yahoo Finance is free, and yahooFinance.quoteSummary('^VIX') works the same as it does for any equity. So every Richfolio run now fetches VIX, the 10-year Treasury yield, S&P 500, oil (WTI), and the USD index (DXY) — five extra calls — and pipes them as a MACRO ENVIRONMENT: preamble into both the observation and decision prompts.

This is OpenAlice’s “equity research” influence translated to a portfolio context. The macro block lets Gemini write things like “elevated VIX + high yields suggest defensive positioning” instead of generic boilerplate, and gates STRONG BUYs more conservatively in high-volatility environments.

Case study: fixing the BSV “75% BUY every day” problem

The patterns above sound abstract. v1.6 was a concrete test of whether they paid off.

Since v1.4 (which introduced the bond ETF framework back in early April), my morning email had this same line every single day:

BSV — 75% BUY — Systematic accumulation to fill 5% allocation gap.

The reason was an over-rigid prompt rule. BSV is a short-duration bond ETF — it has a ~2% annual price range, and equity-style signals like RSI and MACD are noise on a security that barely moves. So I’d hard-coded a confidence formula by allocation gap:


Gap ≥ 5%: confidence 70-75%
Gap 3-5%: confidence 60-70%
Gap 1-3%: confidence 45-55%
Gap &lt; 1%: HOLD

That removed false momentum signals but flatlined the output. With a steady ~5% gap, the answer was 75% every day forever.

The fix needed some timing signal. Just not equity timing signals. After thinking about what actually matters when buying bond ETFs, three orthogonal signals fell out.

1. Price percentile in a rolling 90-day window. Where today’s price sits in BSV’s recent range. Computed from existing chart data:


let pricePercentile90d: number | null = null;
if (closes.length >= 90) {
  const last90 = closes.slice(-90);
  const min90 = Math.min(...last90);
  const max90 = Math.max(...last90);
  if (max90 > min90) {
    pricePercentile90d =
      Math.round(((currentPrice - min90) / (max90 - min90)) * 1000) / 10;
  }
}

2. 10-year Treasury yield direction. Bonds get cheaper when rates rise. I added a 20-trading-day delta on the existing macro fetch:


case "treasury10y": {
  indicators.treasury10y = Math.round(price * 100) / 100;
  const period1 = new Date();
  period1.setDate(period1.getDate() - 35);
  const chart = await yahooFinance.chart(ticker, {
    period1, period2: new Date(), interval: "1d",
  });
  const closes = (chart.quotes ?? [])
    .map(q => q.close)
    .filter((c): c is number => c != null);
  if (closes.length >= 21) {
    indicators.treasury10yChange20d =
      Math.round((closes.at(-1)! - closes.at(-21)!) * 1000) / 1000;
  }
  break;
}

3. Distribution yield level. Yahoo’s summaryDetail.yield returns the SEC / 12-month yield for funds. High yield = high income premium.

Then a new prompt framework that scores via base + timing modifiers :


12a. SHORT-DURATION BOND ETFs:
  BASE (from gap): 5%→55, 3-5%→45, 1-3%→35, &lt;1%→HOLD
  + 90d percentile: ≤20% +12, ≥80% -15
  + 10Y 20d change: >+0.15% +6, &lt;-0.15% -12
  + Yield: >4.5% +3, &lt;3% -2

On a great day for BSV — near 90-day low, rates spiking, high yield, big gap — confidence reaches ~90. On a bad day — top of range, rates falling — it drops to ~25. Real day-to-day variance.

This is where the architectural patterns paid off. The bond ETF rewrite is exactly the kind of change I’d previously been nervous to ship — the AI could ignore the new modifiers and hallucinate a STRONG BUY on BSV, which I never want. But the guard pipeline catches it:


for (const rec of recs) {
  if (!SHORT_DURATION_BOND_ETFS.has(rec.ticker.toUpperCase())) continue;

  if (rec.action === "STRONG BUY") rec.action = "BUY";
  if (rec.suggestedLimitPrice && rec.suggestedLimitPrice > 0) {
    rec.suggestedLimitPrice = 0;
    rec.limitPriceReason = "";
  }
  if (rec.confidence > 95) rec.confidence = 95;
}

And the action-tier sort (new in v1.6) means even if BSV’s confidence reaches 90 on a great day, equity STRONG BUYs still rank above it visually:


const ACTION_PRIORITY: Record<string, number> = {
  "STRONG BUY": 0, BUY: 1, HOLD: 2, WAIT: 3,
};
recommendations.sort((a, b) => {
  const pa = ACTION_PRIORITY[a.action] ?? 99;
  const pb = ACTION_PRIORITY[b.action] ?? 99;
  if (pa !== pb) return pa - pb;
  return b.confidence - a.confidence;
});

The whole BSV fix was about 200 lines of code across four files. The reason it was easy: the guards layer meant I could trust prompt changes to fail safe.

Other things shipped since v1.0

Beyond the architecture and the bond ETF case study, a lot of smaller features landed across v1.1 through v1.6:

Earnings calendar guard — Yahoo’s calendarEvents module ships next-earnings date inside the existing quoteSummary call. Hard HOLD ≤3 days to earnings, no STRONG BUY ≤7.
News sentiment scoring — every headline tagged bullish/bearish/neutral with high/medium/low impact, in the same Gemini call that was already filtering relevance.
Technical indicators expanded — beyond SMA/RSI from v1: MACD with crossover detection, Bollinger Bands with squeeze detection, ATR, Stochastic, OBV trend. All from existing chart data.
Value investing framework — A–D fundamental ratings for individual stocks based on ROE, debt/equity, FCF, growth, analyst target.
Crypto bottom-fishing model — RSI + volume contraction + 200MA + death cross confluence detection for BTC/ETH.
STRONG BUY analysis pages — interactive TradingView chart + buy thesis + risk analysis per STRONG BUY ticker, all encoded in the URL hash (no server).
Refresh mode — re-analyze a single ticker with after-hours / pre-market price for late-night decisions.
Intraday alerts — only fire on STRONG BUY changes (upgrade, downgrade, or ≥10pt confidence shift). No noise.
International currency support — non-USD portfolios fully supported with live FX from Yahoo. Sub-unit handling for exchanges quoting in pence/agorot/cents (LSE GBp → GBP ÷100).
CI + tests — 63 unit tests via node:test, zero dependencies, runs on every PR.
i18n docs — full English / Simplified Chinese / Traditional Chinese site via Jekyll polyglot.

Full release notes are on GitHub Releases.

The honest results so far

I’ve been running Richfolio against my own portfolio for the past few months. Across that window I’m up roughly 6% from acting on the AI’s STRONG BUY suggestions.

The caveat I have to put in writing: US markets have been strong over the same window. A meaningful chunk of that 6% is probably tailwind. I can’t say “the AI added 6%” — I can only say “following the AI’s suggestions during a strong market gave me 6% on those entries.”

To know whether Richfolio actually adds value vs riding the tape, I need to see it run against portfolios that look nothing like mine.

Alpha testers wanted

If you’d like to point Richfolio at your portfolio for a few weeks and tell me where it’s wrong, I’d love to hear from you.

What I’d love testers to bring:

A portfolio that looks different from mine — heavy crypto, sector-concentrated, dividend-focused, international, REIT-heavy, small-cap heavy
Honesty about whether the STRONG BUY signal actually matches what you’d buy yourself
Bug reports — weird tickers, exchanges I don’t trade on, edge cases in the FX layer

What you get:

A working free-tier portfolio monitor
A 1-on-1 setup walkthrough
Direct line to me for feedback and feature requests
First look at upcoming versions

Setup is a GitHub fork plus a few environment variables — full docs at furic.github.io/richfolio.

DM me or open an issue on the repo if you’re interested.

The post Richfolio, three months in: AI architecture in production 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.

The FTX Collapse Had Warnings. An LLM Could Have Caught Them.

Richard Fu — Thu, 05 Mar 2026 12:58:41 +0000

Turning RSS feeds, Google Gemini, and a GitHub cron job into an early warning system for crypto exchange risk.

In November 2022, a cascade of news headlines told the story of FTX’s collapse in slow motion. Alameda’s balance sheet leaked on November 2nd. Binance announced it was dumping FTT on the 6th. By the 8th, withdrawal delays were making headlines. On the 11th, FTX filed for bankruptcy.

Nine days. The signals were public, scattered across CoinTelegraph, Decrypt, The Block, and Google News. But most people — myself included — weren’t synthesizing that information fast enough. The problem wasn’t access. It was attention.

That observation sat with me for a while. Not as a regret, but as an engineering question: what would it take to automate the “paying attention” part?

The answer turned out to be surprisingly small. About 450 lines of TypeScript, three npm dependencies, and an LLM that’s good at reading headlines.

The Bet: LLMs as Risk Filters, Not Risk Analyzers

There’s a temptation to over-scope AI in financial applications — building trading bots, predicting prices, replacing analysts. Most of those projects fail because they ask the AI to be right about uncertain things.

Crypto Sentinel takes a different bet: use the LLM as a filter , not an oracle. It doesn’t predict what will happen. It reads a batch of headlines and answers one narrow question: does this collection of news suggest elevated risk for the exchanges I hold funds on?

That’s a classification task, not a prediction task. And classification is something current LLMs do reliably.

The system defines five risk tiers with explicit criteria:

Level	Trigger Examples
Critical	Insolvency, confirmed hack, withdrawal freeze, regulatory shutdown
High	Major security breach, regulatory enforcement, suspected bank run
Medium	Regulatory investigation, partnership failure, leadership departure
Low	Minor negative press, market downturn, routine operational changes
None	Neutral or positive coverage

Only medium and above triggers an alert. This single design choice — an aggressive threshold — is what prevents the system from becoming noise. Every notification that reaches my phone is worth reading.

Architecture: Six Stages, No Server

The entire pipeline runs as a scheduled GitHub Actions job, four times a day. There’s no always-on server, no database, no container orchestration. Here’s the flow:


RSS Feeds ──> Keyword Filter ──> Dedup Cache ──> Gemini Analysis ──> Alerts
 (5 sources (configurable (MD5 of URL, (structured (email via
 + Google watchlist) last 500) JSON output) Resend +
   News) Telegram)

Each stage is a single TypeScript module. The orchestrator in index.ts is 59 lines — a for loop with error handling. Let’s walk through the interesting parts.

Aggregation: RSS + Google News with a Redirect Trap

Four crypto-focused RSS feeds provide the baseline coverage:


const RSS_FEEDS = [
  { source: "CoinTelegraph", url: "https://cointelegraph.com/rss" },
  { source: "Decrypt", url: "https://decrypt.co/feed" },
  { source: "The Block", url: "https://www.theblock.co/rss.xml" },
  { source: "CryptoSlate", url: "https://cryptoslate.com/feed/" },
];

Google News adds broader coverage, dynamically querying for each watched keyword (“bybit crypto”, “youhodler crypto”, etc.). But there’s a trap here that took some debugging.

Google News RSS doesn’t serve direct article URLs. Every link is a redirect wrapper: news.google.com/rss/articles/CBMi.... In a browser, this transparently redirects to the real article. But email services like Resend wrap outbound links in their own click-tracking redirect. So clicking a link in the email creates a double redirect : Resend → Google News → actual article. Google interprets that chain as bot traffic and blocks it with a CAPTCHA page.

The fix resolves Google News URLs at ingestion time, before they ever reach the email:


const resolveGoogleNewsUrl = async (url: string): Promise<string> => {
  try {
    const res = await fetch(url, { method: "HEAD", redirect: "follow" });
    if (res.url && res.url !== url) return res.url;
  } catch {
    try {
      const res = await fetch(url, { redirect: "manual" });
      const location = res.headers.get("location");
      if (location) return location;
    } catch { /* fall through */ }
  }
  return url;
};

The HEAD-first approach minimizes bandwidth. If the server doesn’t support HEAD (some don’t), it falls back to a manual redirect extraction. Worst case, the original Google News URL passes through unchanged.

All resolutions happen in parallel via Promise.all, so this doesn’t meaningfully slow down the pipeline.

Deduplication: MD5 Hashing with a Rolling Window

Each article is identified by the MD5 hash of its resolved URL. A JSON file caches the last 500 seen hashes — roughly a week of coverage at current volume. The cache is persisted between GitHub Actions runs using actions/cache@v4 with a rolling key strategy:


- uses: actions/cache@v4
  with:
    path: cache.json
    key: sentinel-cache-${{ github.run_id }}
    restore-keys: sentinel-cache-

Every run creates a new cache key (by run ID), but restores from the most recent one. This means the cache auto-updates without manual pruning of stale keys.

Why not a database? Because a 16 KB JSON file with 500 hex strings doesn’t need one. The entire state model fits in a single fs.readFileSync call.

The Gemini Prompt: Structured Output via Role-Playing

The prompt engineering is deliberate. Rather than asking Gemini to “analyze these headlines,” it’s given an explicit role and output contract:


const prompt = `You are a crypto-exchange risk analyst. Given these headlines
about crypto exchanges, assess the overall risk level.

Risk levels:
- CRITICAL: insolvency, confirmed hack, withdrawal freeze, regulatory shutdown
- HIGH: major security breach, regulatory enforcement, suspected bank run
- MEDIUM: regulatory warning, partnership failure, major leadership departure
- LOW: minor negative press, market downturn, routine changes
- NONE: neutral news, positive coverage

Headlines:
${headlines.map((h, i) => `${i + 1}. ${h}`).join("\n")}

Return ONLY valid JSON:
{ "risk_level": "...", "summary": "1-2 sentence summary", "alerts": ["concern 1", ...] }`;

Three things matter here:

Enumerated risk levels with examples — removes ambiguity about what “high” means
Numbered headlines — helps the model reference specific items in its summary
“Return ONLY valid JSON” — reduces the chance of markdown wrappers or preamble text

When JSON parsing fails (it happens ~2% of the time with Flash models), the system falls back to low risk with a manual review flag rather than crashing.

Alert Formatting: Color-Coded HTML for Fast Scanning

The email alert is designed to be scannable in under 10 seconds. A color-coded header immediately communicates severity:


const riskColors: Record<RiskLevel, string> = {
  critical: "#dc2626", // Red — immediate action
  high: "#ea580c", // Orange — urgent attention
  medium: "#d97706", // Amber — worth investigating
  low: "#65a30d", // Green — low concern
  none: "#6b7280", // Gray — informational
};

Below the header: AI summary, specific concerns as bullets, and a table of source articles with direct links. Telegram gets a condensed version — same information hierarchy, fewer articles (10 vs 20), plain text formatting.

Telegram is entirely optional and implemented with raw fetch() against the Bot API. No SDK, no npm dependency. If the env vars aren’t configured, it silently skips. If the API call fails, the error is logged but doesn’t block the email alert.

Resilience as a Feature

A monitoring system that crashes is worse than no monitoring system — it gives false confidence. Every stage in the pipeline is designed to degrade rather than fail:

Failure	Behavior
One RSS feed times out	Other feeds still process; warning logged
Google News returns 403	Skipped; dedicated feeds provide baseline coverage
Gemini returns invalid JSON	Falls back to `low` risk + manual review flag
Resend API error	Hard fail (email is the primary channel — this should be loud)
Telegram API error	Logged, not propagated; email already sent
Cache file missing/corrupt	Starts fresh; may re-alert on seen articles (acceptable)

The only intentional hard failures are missing API keys for Gemini and Resend. Everything else bends rather than breaks.

The Stack, and Why Each Piece

Component	Choice	Alternative Considered	Why This One
Language	TypeScript (strict)	Python	Type safety for AI response parsing; catches schema mismatches at compile time
AI model	Gemini 2.5 Flash	GPT-4o-mini, Claude Haiku	Generous rate limits on the free tier (250 req/day); sub-second for classification
Email	Resend	SendGrid, AWS SES	Simplest API surface; works without domain verification via shared sender
Messaging	Telegram Bot API	Slack, Discord	Native mobile push; no OAuth dance; direct `fetch()` with zero dependencies
RSS parsing	rss-parser	feedparser, custom	Handles RSS 2.0 and Atom; tolerant of malformed feeds; 10s timeout built in
Scheduling	GitHub Actions cron	AWS Lambda, Vercel cron	Secrets management built in; cache persistence built in; already where the code lives
Persistence	JSON file	SQLite, Redis	16 KB of data doesn’t justify a database; human-readable for debugging

Total production dependencies: @google/generative-ai, resend, rss-parser. That’s it. Everything else is native Node.js 22 (including fetch).

Gotchas Worth Knowing

A few things that weren’t obvious upfront:

Google News RSS is region-locked. The ceid and gl parameters control which regional edition you get. AU:en returns Australian English results. If you’re watching for news about a Southeast Asian exchange, you might want SG:en or multiple regional queries.

Resend’s click tracking creates double redirects. Any URL in a Resend email gets wrapped in a resend-clicks.com tracking redirect. If the original URL is also a redirect (like Google News), the target server may block the chained request. Always resolve redirects before including URLs in emails.

LLM JSON output isn’t guaranteed. Even with explicit “return ONLY valid JSON” instructions, Gemini occasionally wraps the response in markdown code fences or adds a preamble. The JSON.parse call needs a try/catch with a sensible fallback — not just for robustness, but because the failure mode (crashing at 3 AM with no alert) is worse than the degraded mode (a slightly less precise risk assessment).

GitHub Actions cron is approximate. The schedule trigger doesn’t guarantee exact timing — GitHub queues jobs, and during high load, runs can be delayed by 15-30 minutes. For a monitoring system that runs 4x daily, this is fine. For anything requiring precise timing, it’s not.

actions/cache has a 10 GB limit per repo. With a rolling key strategy, old cache entries accumulate. For a 16 KB file this is irrelevant, but worth knowing if you extend the pattern to larger datasets.

The Broader Pattern

Strip away the crypto-specific parts and what remains is a general-purpose architecture for AI-augmented monitoring of public information :

Aggregate from multiple public data sources (RSS, APIs, web scraping)
Filter by relevance criteria (keywords, rules, heuristics)
Deduplicate against a rolling history to avoid re-processing
Classify using an LLM with structured output and explicit criteria
Route alerts conditionally based on severity thresholds
Deliver through multiple channels with graceful degradation

This same pipeline could monitor:

Competitor news for a product team
Regulatory filings in a specific industry
Security advisories for your dependency stack
Brand mentions across news outlets
Supply chain disruptions for logistics operations

The LLM is the key differentiator from traditional keyword alerts. It can distinguish between “Exchange X partners with major bank” (positive) and “Exchange X under investigation by major bank regulator” (concerning) — something a keyword filter fundamentally cannot do.

Try It

The project is open source and designed to be forked. Three API keys (all free-tier, no credit card), a few GitHub secrets, and you have a running monitor.

Repository: github.com/furic/crypto-sentinel

Docs: furic.github.io/crypto-sentinel


# Local development
git clone https://github.com/furic/crypto-sentinel.git
cd crypto-sentinel &amp;&amp; npm install
cp .env.example .env # Add your API keys
npm run dev

The whole thing is ~450 lines of TypeScript. Read it in an afternoon, fork it, make it yours.

The next exchange collapse will have warning signs. The question is whether you’ll be reading headlines fast enough to notice them.

The post The FTX Collapse Had Warnings. An LLM Could Have Caught Them. appeared first on Richard Fu.

I Built a Free AI Portfolio Assistant That Emails Me Every Morning

Richard Fu — Wed, 25 Feb 2026 14:57:44 +0000

I wanted to start building my investment portfolio by the end of the year. The problem? I don’t have time to monitor stock prices, read financial news, and analyze market data every day — and I don’t have the expertise to do it well.

What I wanted was simple: wake up, check my email, and know exactly what’s happening with my portfolio and what I should buy. And if something changes during the day — a price dip, a strengthening signal — I want to know before I miss it.

I looked at a lot of open-source projects. Some did portfolio tracking. Some did news aggregation. Some did basic alerts. But none did everything I wanted, and none were flexible enough to customize the output. I wanted full control over what data gets analyzed, how the AI reasons about it, and exactly what gets sent to me.

Most importantly — I wanted it free. And it turns out that’s entirely achievable with Yahoo Finance, Gemini’s free tier, and GitHub Actions.

So I built Richfolio — a zero-maintenance AI portfolio assistant — with Claude in a few sessions.

What It Does

Richfolio is a single TypeScript pipeline. It runs once, produces a report, and exits. No API server, no database, no background processes.

Every morning at 8am , GitHub Actions triggers the pipeline:

Fetches live prices, P/E ratios, 52-week ranges, ETF holdings (Yahoo Finance)
Computes technical indicators — SMA50, SMA200, RSI, momentum (Yahoo Finance chart data)
Pulls news headlines per ticker (NewsAPI)
Analyzes allocation gaps, P/E signals, ETF overlap against my target portfolio
Sends everything to Gemini, which returns ranked buy recommendations with confidence scores, reasoning, and limit order prices
Delivers via email and Telegram

Every 2–3 hours during market hours , it re-runs in intraday mode — comparing against the morning baseline and only alerting me when signals strengthen. No change = no message.

Every Monday , a weekly rebalancing report shows what’s drifted from target — BUY, TRIM, or OK.

The Pipeline

The whole system is one index.ts that wires independent modules together:


const tickers = allUniqueTickers();
const prices = await fetchAllPrices(tickers);
const report = runAnalysis(prices);

// Daily mode: full brief with news + AI + technicals
const [news, technicals] = await Promise.all([
  fetchNews(tickers),
  fetchTechnicals(tickers),
]);
const aiRecs = await aiAnalyze(report, prices, news, technicals);

// Save morning baseline for intraday comparison
saveBaseline({
  timestamp: new Date().toISOString(),
  recommendations: aiRecs,
  prices: priceMap,
});

await sendBrief(report, news, aiRecs, technicals);
await sendTelegramBrief(report, news, aiRecs, technicals);

Each module does one thing — fetch prices, compute technicals, run AI, send email. They communicate through typed interfaces and don’t know about each other. This makes it trivial to add new data sources or delivery channels.

Technical Indicators From Scratch

I didn’t want to add a charting library dependency for what’s essentially just math. Richfolio fetches 250 days of daily price data from Yahoo Finance and computes everything directly:


function computeSMA(prices: number[], period: number): number | null {
  if (prices.length < period) return null;
  const slice = prices.slice(-period);
  return slice.reduce((sum, p) => sum + p, 0) / period;
}

function computeRSI(prices: number[], period: number = 14): number | null {
  if (prices.length < period + 1) return null;

  const recent = prices.slice(-(period + 1));
  let avgGain = 0;
  let avgLoss = 0;

  for (let i = 1; i < recent.length; i++) {
    const change = recent[i] - recent[i - 1];
    if (change > 0) avgGain += change;
    else avgLoss += Math.abs(change);
  }

  avgGain /= period;
  avgLoss /= period;

  if (avgLoss === 0) return 100;
  const rs = avgGain / avgLoss;
  return 100 - 100 / (1 + rs);
}

From these primitives, I classify each ticker’s momentum:


let momentumSignal: "bullish" | "bearish" | "neutral" = "neutral";

if (currentPrice > sma50 && (sma200 == null || sma50 > sma200) && rsi14 > 40) {
  momentumSignal = "bullish";
} else if (currentPrice < sma50 && sma200 != null && sma50 < sma200 && rsi14 < 60) {
  momentumSignal = "bearish";
}

It also tracks 7-day and 30-day lows as support levels, and detects golden/death crosses (SMA50 crossing SMA200). All of this feeds into the AI prompt for smarter recommendations.

The AI Prompt

The AI layer is where everything comes together. Gemini receives the full context for every ticker — fundamentals, technicals, allocation data, and news — in a structured prompt:


function buildPrompt(report, priceData, news, technicals) {
  const tickerSummaries = report.items.map((item) => {
    const quote = priceData[item.ticker];
    const tech = technicals[item.ticker];

    const lines = [
      `${item.ticker}:`,
      ` Price: $${item.price.toFixed(2)}`,
      ` Trailing P/E: ${quote?.trailingPE?.toFixed(1) ?? "N/A"}`,
      ` 52-week position: ${(item.fiftyTwoWeekPercent * 100).toFixed(0)}%`,
      ` Current allocation: ${item.currentPct.toFixed(1)}% (target: ${item.targetPct.toFixed(1)}%, gap: ${item.gapPct.toFixed(1)}%)`,
    ];

    if (tech) {
      lines.push(` Technical indicators:`);
      lines.push(` 50-day MA: $${tech.sma50} (price ${tech.priceVsSma50}% vs MA)`);
      lines.push(` RSI(14): ${tech.rsi14}`);
      lines.push(` Momentum: ${tech.momentumSignal}`);
      lines.push(` 7-day low: $${tech.recentLow7d}, 30-day low: $${tech.recentLow30d}`);
    }

    return lines.join("\n");
  });
  // ... instructions follow
}

The instructions tell Gemini to consider allocation need AND valuation together — a small gap with great valuation should rank above a large gap with poor valuation. It also asks for limit order prices based on nearby support levels:


8. For STRONG BUY and BUY tickers, suggest a limit order price slightly below
   current market. Base it on the nearest support level: 50-day MA, recent
   7d/30d low, or a round number.
9. Use technical indicators (MA, RSI, momentum) to refine confidence. A bullish
   momentum signal with oversold RSI strengthens a buy case.

Gemini returns structured JSON using a defined schema, so parsing is reliable:


const response = await ai.models.generateContent({
  model: "gemini-2.5-flash",
  contents: prompt,
  config: {
    responseMimeType: "application/json",
    responseSchema,
  },
});

const recommendations = JSON.parse(response.text ?? "[]");

Each recommendation includes an action (STRONG BUY/BUY/HOLD/WAIT), confidence score, reasoning, suggested dollar amount, limit order price, and the reasoning behind the limit price. No free-text parsing needed.

If Gemini is down or quota is exhausted, the system falls back to gap-based recommendations. The brief still gets delivered.

ETF Overlap Detection

One feature I’m particularly proud of: if I hold individual stocks that are also inside my ETFs, the system detects the overlap and adjusts buy suggestions.


// ETF overlap discount
if (quote.holdings && suggestedBuyValue > 0) {
  for (const h of quote.holdings) {
    const heldShares = currentHoldings[h.symbol] ?? 0;
    const heldQuote = priceData[h.symbol];
    if (heldShares > 0 && heldQuote) {
      const heldValue = heldShares * heldQuote.price;
      const etfExposure = h.holdingPercent * suggestedBuyValue;
      overlapDiscount += Math.min(etfExposure, heldValue);
    }
  }
  suggestedBuyValue -= overlapDiscount;
}

Example: VOO contains ~7% AAPL. If I hold $8,000 in AAPL and VOO’s suggested buy is $10,000, the overlap is min(7% × $10,000, $8,000) = $700. VOO’s suggestion drops to $9,300. This prevents over-concentrating in stocks I already hold directly.

Intraday Alerts: Don’t Miss the Dip

The morning brief is great, but markets move. The intraday system saves the morning AI recommendations as a baseline, then re-runs every 2–3 hours and compares:


const ACTION_RANK = { WAIT: 0, HOLD: 1, BUY: 2, "STRONG BUY": 3 };

for (const rec of currentRecs) {
  const morning = baselineMap.get(rec.ticker);
  const confidenceDelta = rec.confidence - (morning?.confidence ?? 0);
  const actionUpgraded = ACTION_RANK[rec.action] > ACTION_RANK[morning?.action ?? "WAIT"];

  // Trigger 1: Confidence jumped significantly
  if (confidenceDelta >= config.confidenceIncreaseThreshold &&
      rec.confidence >= config.minConfidenceToAlert) {
    triggerType = "confidence_increase";
  }

  // Trigger 2: Action upgraded (e.g., BUY → STRONG BUY)
  if (actionUpgraded && rec.confidence >= config.minConfidenceToAlert) {
    triggerType = "action_upgrade";
  }

  // Trigger 3: New signal that wasn't in morning recs
  if (!morning && rec.confidence >= config.minConfidenceToAlert) {
    triggerType = "new_signal";
  }
}

An alert fires only when something actually improved — confidence increased by 5+ points, an action upgraded, or a new strong signal appeared. All thresholds are configurable. No alert = no message. I only hear from it when it matters.

The Stack (All Free)

This was a key constraint. I wanted zero recurring costs. Here’s what makes it possible:

Service	Purpose	Free Tier
Yahoo Finance (yahoo-finance2)	Prices, fundamentals, technicals, ETF holdings	Unlimited
Google Gemini 2.5 Flash	AI recommendations + limit prices	250 req/day
NewsAPI	Headlines per ticker	100 req/day
Resend	HTML email delivery	3,000/month
Telegram Bot API	Mobile alerts	Unlimited
GitHub Actions	Scheduled cron	2,000 min/month

The runtime is TypeScript + Node.js , executed with tsx — no build step, no compilation. Each module is independent and the whole pipeline runs in ~30 seconds.

For technical indicators, I computed SMA, RSI, and momentum from raw chart data — no charting library needed. For Telegram, I use native fetch instead of adding an npm package. The whole project has only 4 runtime dependencies: yahoo-finance2, @google/genai, resend, and dotenv.

Architecture


src/
├── config.ts # Typed loader for config.json + .env
├── index.ts # Entry point — wires everything together
├── fetchPrices.ts # Yahoo Finance: price, P/E, 52w, beta, dividends, ETF holdings
├── fetchTechnicals.ts # Yahoo Finance chart: SMA50, SMA200, RSI, momentum
├── fetchNews.ts # NewsAPI with ticker-to-company-name mapping
├── analyze.ts # Allocation gaps, P/E signals, ETF overlap, portfolio metrics
├── aiAnalysis.ts # Gemini prompt builder + JSON schema + response parser
├── state.ts # Morning baseline save/load for intraday comparison
├── intradayCompare.ts # Compare current vs morning, detect strengthening
├── email.ts # Daily HTML email template + Resend delivery
├── intradayEmail.ts # Intraday alert email (triggered only)
├── weeklyEmail.ts # Weekly rebalancing email + Resend
└── telegram.ts # Telegram Bot API (daily + intraday + weekly formatters)

Every module exports typed interfaces (QuoteData, TechnicalData, AllocationItem, AIBuyRecommendation, IntradayAlert) and communicates through them. No shared state, no side effects. If a new data source or delivery channel is needed, it’s just a new file that plugs into index.ts.

Configuration

Your portfolio is defined in a single config.json:


{
  "targetPortfolio": {
    "VOO": 20,
    "QQQ": 15,
    "GLD": 10,
    "BSV": 20,
    "BTC": 1.5
  },
  "currentHoldings": {
    "AAPL": 30,
    "VOO": 1,
    "BTC": 0.0002
  },
  "totalPortfolioValueUSD": 50000
}

Target allocations are percentages. Current holdings include stocks not in your target (like AAPL above) — these are tracked for ETF overlap detection. Crypto tickers like BTC are automatically converted to BTC-USD for Yahoo Finance.

In GitHub Actions, this file is stored as a repository variable (CONFIG_JSON) so your portfolio data stays private.

What I Learned

You don’t need a Bloomberg terminal. Yahoo Finance freely provides everything from real-time prices to earnings history to ETF holdings to 250 days of chart data. The AI layer just synthesizes it into actionable recommendations.

Scheduled pipelines are underrated. No server, no uptime concerns, no costs. GitHub Actions runs the cron, the pipeline executes in ~30 seconds, and I get my email. If it fails, it just retries next time.

Free tiers are generous for personal tools. I use ~3 of 3,000 monthly Resend emails and ~10 of 250 daily Gemini requests. The whole stack runs comfortably within free limits.

Technical data makes the AI smarter. Adding SMA, RSI, and momentum to the Gemini prompt noticeably improved recommendations. Instead of just “the allocation gap is large,” the AI now says things like “price near 50-day MA support with RSI at 38 — good entry point for a limit order at $217.”

Structured JSON output from Gemini is a game-changer. Using responseSchema means the AI returns exactly the fields I need — no regex parsing, no “oops it returned markdown this time.” Every response is type-safe and immediately usable.

Graceful degradation matters. Every optional service (Gemini, NewsAPI, Telegram) can be missing or down, and the system still works. The brief adapts to what’s available instead of failing entirely.

Try It

Richfolio is open source. Fork the repo, add your config and API keys, and you’ll have your own AI portfolio assistant by tomorrow morning. Setup takes about 10 minutes.

GitHub: github.com/furic/richfolio

Docs: furic.github.io/richfolio

It’s been running daily and I genuinely look forward to checking my email every morning now — which is probably the first time I’ve ever said that.

The post I Built a Free AI Portfolio Assistant That Emails Me Every Morning 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 / Raw Fun 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://fur-gaming.github.io/blocky-ui/
📦 npm Package : blocky-ui-lite
🐙 GitHub : fuR-Gaming/blocky-ui
📖 Documentation Wiki : GitHub Wiki
🎯 Stack Rush : Original game that inspired the design

🤝 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.

Planet Blue Invasion: Building the Future of Casino Gaming with WebGPU and Three.js

Richard Fu — Fri, 12 Sep 2025 14:03:36 +0000

How we built a cutting-edge 3D Earth simulation casino game using modern web technologies

View Post

As a game developer, I’m excited to share the technical journey behind Planet Blue Invasion , now live on Stake.com. This isn’t just another casino game—it’s a showcase of what’s possible when you combine modern web graphics technology with innovative game design.

The Vision: Alien Invasion Meets Casino Gaming

Planet Blue Invasion puts players in the role of elite alien commanders aboard a war-class spaceship. The gameplay is deceptively simple yet thrilling: spin to target random Earth locations, fire orbital lasers, and earn payouts based on real population density data. Hit Shanghai? Massive payout. Strike the Pacific Ocean? Zero reward.

What makes this special is the underlying technology that creates an immersive, visually stunning experience that feels more like a AAA game than traditional casino fare.

The Tech Stack: Pushing Web Graphics Forward

WebGPU: The Graphics Revolution

At the heart of Planet Blue Invasion is WebGPU —the next-generation graphics API for the web. Unlike WebGL, WebGPU provides:

Native GPU Performance : Direct access to modern GPU features with significantly lower overhead
Advanced Shading : Complex material systems with better performance
Future-Proof Architecture : Built for modern GPUs and rendering pipelines

We’re using Three.js’s WebGPU renderer, which puts us at the forefront of web graphics technology. The Earth you see isn’t just a textured sphere—it’s a multi-layered planetary system with:

Dynamic day/night cycles
Realistic atmospheric scattering
Volumetric cloud rendering
Surface detail mapping with bump effects

TSL (Three Shading Language): Node-Based Materials

One of the most exciting aspects of development was using TSL (Three Shading Language). This node-based material system allows us to create complex shaders visually:


// TSL material example for Earth's day/night blending
const earthMaterial = new TSLMaterial({
  nodes: {
    diffuse: mix(
      texture(dayTexture, uv()),
      texture(nightTexture, uv()),
      sunDirection.dot(normal).add(0.5)
    ),
    normal: texture(bumpTexture, uv()).xyz.mul(2).sub(1)
  }
});

This approach gives us real-time material editing capabilities and better performance than traditional GLSL shaders.

TypeScript: Type Safety in Complex Systems

With a game this complex, TypeScript was essential. Our architecture includes:

Strict typing for 3D math operations
Interface contracts between game systems
Compile-time safety for API integrations

The population data system, for example, handles millions of coordinate lookups with complete type safety:


interface LocationData {
  latitude: number;
  longitude: number;
  population: number;
  city: string;
  country: string;
  payoutMultiplier: number;
}

The fuR Gaming Engine: Framework-Agnostic Architecture

Planet Blue Invasion is built on our proprietary fuR Gaming Engine —a framework-agnostic system designed specifically for casino games. The engine provides:

Internationalization (i18n) System

16 language support including RTL languages like Arabic
Dynamic loading with fallback chains
Cultural adaptation for different markets

Audio System

Spatial audio effects for orbital laser sounds
Dynamic music that responds to game states
Howler.js integration for web audio optimization

Math & RTP System

Provably fair mathematics with 97% RTP
Weight distribution algorithms for balanced gameplay
Population-based payout calculations

Real-World Data Integration

One of the most challenging aspects was integrating real population data. Our system:

Uses GeoNames database with 32,283 cities having 15K+ population
Queries random coordinates via BigDataCloud and Nominatim APIs
Validates location data – locations without city/country data become “empty payout” entries
Calculates realistic payouts based on actual population density from GeoNames

The formula is elegantly simple: Math.round((population / 100000) * 100), making Shanghai, 24.87M population, the theoretical maximum payout at 248.74x.

Performance Optimizations

Asset Management

Relative path architecture for CDN compatibility
Texture optimization with 4K Earth textures compressed efficiently
Progressive loading for smooth startup experience

Rendering Pipeline

Level-of-detail (LOD) systems for Earth surface detail
Frustum culling for off-screen elements
Batch rendering for UI elements

The Casino Gaming Mathematics

Behind the stunning visuals lies sophisticated gambling mathematics:

Target RTP: 97% – Industry-leading return to player
Hit Rate: 33% – Balanced win frequency
Tier Distribution :
- No Win: 67% (Ocean/uninhabited)
- Small Wins: 23.1% (1x-10x)
- Medium Wins: 8.25% (10x-100x)
- Big Wins: 1.65% (100x+)

Our analytics system continuously verifies these mathematics to ensure fair, engaging gameplay.

Bonus Features: Super Spin Mode – Human Radar

The “Super Spin Mode: Human Radar” showcases our engine’s capabilities:

Smart Targeting – Advanced alien technology detects human settlements before firing
Guaranteed Impact – Every shot hits a populated zone, no wasted ammunition
Premium Cost – Activate for 2x base bet to access elite targeting system
Higher Rewards – Focus destruction on densely populated areas for maximum devastation

Development Workflow

Our development setup prioritizes modern tooling:

Vite for lightning-fast development builds
Local Three.js builds for WebGPU feature access
GLSL shader integration with hot reloading
Automated testing for gambling mathematics verification

Play Planet Blue Invasion Today

Planet Blue Invasion represents what’s possible when you combine cutting-edge web technology with innovative game design. Every spin is a journey through real Earth data, every win is backed by provably fair mathematics, and every visual effect is rendered using the latest WebGPU technology.

Experience Planet Blue Invasion on Stake.com

Whether you’re a fellow developer curious about WebGPU implementation, a gaming enthusiast looking for the next evolution in casino games, or someone who simply enjoys blowing up virtual Earth locations for profit—Planet Blue Invasion delivers.

Technical Resources

For developers interested in the technologies used:

Ready to join the alien invasion? The Earth is waiting…

The post Planet Blue Invasion: Building the Future of Casino Gaming with WebGPU and Three.js appeared first on Richard Fu.