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

Introducing Cosmic UI Lite: A Zero-Dependency Space-Themed UI Library

Richard Fu — Mon, 01 Sep 2025 09:30:55 +0000

Ever needed a futuristic, sci-fi UI for your web project but found existing solutions too heavyweight or framework-dependent? That’s exactly the problem I faced when building my game project. Today, I’m excited to introduce Cosmic UI Lite – a lightweight, zero-dependency TypeScript UI component library designed for space-themed interfaces.

🌟 Try the Live Demo | 📦 NPM Package | 📚 GitHub Repository

💡 The Motivation

While working on my game project, I discovered rizkimuhammada/cosmic-ui – a beautiful cosmic-themed UI library. However, it had some limitations for my use case:

React Dependency : My game was built with vanilla TypeScript
Feature Bloat : I only needed a handful of essential components
Bundle Size : Needed something lightweight for game performance
Build Complexity : Wanted a simple, drop-in solution

So I decided to create a focused alternative that prioritizes simplicity, performance, and universal compatibility.

🛠️ The Technology Behind Cosmic UI Lite

SVG-Based Dynamic Rendering

The heart of Cosmic UI Lite lies in its dynamic SVG generation system. Instead of using static images or complex CSS tricks, every component creates its cosmic borders and backgrounds programmatically:


// SVG elements are created on-the-fly
const backgroundSvg = createSvgElement('cosmic-bg', '0 0 474 332');
const gradient = createGradient('cosmicGradient', [
  { offset: '0%', color: '#1a1a2e' },
  { offset: '50%', color: '#2a2a4e' },
  { offset: '100%', color: '#1a1a2e' }
]);

This approach provides several advantages:

Scalability : Vector graphics look crisp at any size
Customization : Colors and gradients can be modified programmatically
Performance : No external image dependencies to load
Consistency : Unified shape language across all components

Four-Layer Architecture

Each component follows a consistent 4-layer structure:

Wrapper Element : Container with positioning and hover effects
SVG Background : Animated gradient fill with cosmic patterns
SVG Border : Glowing outline that responds to interactions
Content Layer : Text, buttons, and interactive elements

Zero Dependencies Philosophy

Cosmic UI Lite is built with pure TypeScript and vanilla JavaScript – no runtime dependencies whatsoever. This means:

✅ Universal Compatibility : Works with any framework or vanilla JS
✅ Tiny Bundle Size : No dependency tree bloat
✅ Security : No supply chain vulnerabilities
✅ Reliability : Won’t break due to dependency updates

🎨 Component Showcase

Cosmic Button

Animated buttons with hover effects and multiple variants:


import { CosmicUI } from 'cosmic-ui-lite';

const launchButton = CosmicUI.createButton({
  text: '🚀 Launch Mission',
  variant: 'primary',
  onClick: () => console.log('Mission started!')
});

document.body.appendChild(launchButton);

Cosmic Modal

Full-featured modals with backdrop blur and cosmic styling:


const confirmModal = CosmicUI.createModal({
  title: 'Mission Control',
  content: `
    <p>Are you ready to launch the mission?</p>
    <p>This action cannot be undone.</p>
  `,
  buttons: [
    {
      text: 'Cancel',
      variant: 'secondary',
      onClick: () => console.log('Cancelled')
    },
    {
      text: 'Launch',
      variant: 'danger',
      onClick: () => console.log('Launching!')
    }
  ]
});

CosmicUI.showModal(confirmModal);

Utility Methods

Built-in utilities for common patterns:


// Quick confirmation dialog
CosmicUI.showConfirmation(
  'Delete Save File',
  'This will permanently delete your progress.',
  () => console.log('Deleted'),
  () => console.log('Cancelled')
);

// Error notifications
CosmicUI.showError(
  'Connection Lost',
  'Unable to connect to mission control.',
  () => console.log('Acknowledged')
);

🎯 Perfect for Game Development

Cosmic UI Lite was specifically designed with game development in mind:

Performance Optimized : Lightweight components that don’t impact game performance
Thematic Consistency : Space/sci-fi aesthetic perfect for space games, RPGs, and strategy games
Framework Agnostic : Works with any game engine that supports web technologies
Responsive Design : Adapts to different screen sizes and device types

🚀 Getting Started

Installation


# NPM
npm install cosmic-ui-lite

# Yarn
yarn add cosmic-ui-lite

# CDN
<script src="https://unpkg.com/cosmic-ui-lite@latest/dist/index.umd.js"></script>

Basic Usage


import { CosmicUI } from 'cosmic-ui-lite';
// CSS is automatically imported

// Create a space dashboard
const statusCard = CosmicUI.createCard({
  title: 'Ship Status',
  content: `
    <p><strong>Hull Integrity:</strong> <span style="color: #00ff88;">100%</span></p>
    <p><strong>Power Level:</strong> <span style="color: #00d4ff;">Optimal</span></p>
    <p><strong>Shields:</strong> <span style="color: #ffaa00;">Charging</span></p>
  `
});

document.body.appendChild(statusCard);

🎨 Visual Design Philosophy

The visual design draws inspiration from classic sci-fi interfaces with modern web standards:

Angled Corners : Distinctive beveled edges that evoke spaceship control panels
Animated Gradients : Subtle particle-like animations that bring interfaces to life
Cosmic Color Palette : Deep space blues, electric cyans, and warning oranges
Glowing Effects : Subtle borders that pulse and respond to user interaction

📊 Technical Specifications

📦 Bundle Size : ~15KB minified + gzipped
🎯 TypeScript : Full type safety with comprehensive interfaces
🌐 Browser Support : All modern browsers (ES2020+)
📱 Responsive : Mobile-first design with adaptive layouts
♿ Accessible : WCAG-compliant with keyboard navigation
⚡ Performance : Zero-dependency, optimized for games

🔮 Future Roadmap

While Cosmic UI Lite is designed to stay lightweight, there are some exciting possibilities on the horizon:

Theme System : Multiple cosmic color schemes
Animation Presets : Configurable animation intensity levels
Component Extensions : Additional specialized components based on community feedback
Framework Integrations : Optional wrappers for React, Vue, and Angular

🌟 Try It Today!

Ready to add some cosmic flair to your next project? Check out these resources:

🌐 Interactive Demo – Try all components live
📦 NPM Package – Install with your favorite package manager
📚 Documentation – Complete guides and examples
🛠️ GitHub Repository – Source code and issue tracking

Whether you’re building a space exploration game, a sci-fi web application, or just want to add some futuristic flair to your project, Cosmic UI Lite provides the perfect balance of visual impact and technical simplicity.

What kind of cosmic interfaces will you build? I’d love to see your creations – share them in the comments below or tag me on social media!

Cosmic UI Lite is open source and available under the MIT License. Contributions, feedback, and cosmic creativity are always welcome! 🚀

The post Introducing Cosmic UI Lite: A Zero-Dependency Space-Themed UI Library appeared first on Richard Fu.

Building an Automated LeetCode Solution Post Sync Feature for LeetHub

Richard Fu — Tue, 29 Jul 2025 14:09:39 +0000

As a passionate LeetCode enthusiast, I tackle the daily coding challenge religiously and share my solution insights with the community through detailed posts (often polished with AI assistance). My coding journey is powered by LeetHub, an incredible Chrome extension that automatically synchronizes my LeetCode solutions to my GitHub repository, helping me build a robust coding portfolio over time.

However, I noticed a gap in my workflow. While LeetHub excellently captures my code solutions as plain script files, my thoughtful solution explanations—complete with intuition, approach breakdowns, and complexity analysis—were stuck on LeetCode’s platform. I found myself manually copying these posts to create Solution.md files in my GitHub repo, which was both tedious and inconsistent.

That’s when it hit me: why couldn’t LeetHub handle this automatically? This realization sparked my journey to extend LeetHub’s capabilities, and today I’m excited to share the story of building an automated solution post sync feature that bridges this gap.

How the Feature Works

The new feature operates seamlessly in the background, requiring zero additional effort from users:

Detection : When you publish a solution post on LeetCode, the extension automatically detects the action by intercepting the GraphQL request
Content Extraction : It captures your solution title, content, and problem metadata from the request payload
Smart Mapping : The extension maps the LeetCode problem slug to your existing GitHub repository folder structure
Commit Message Consistency : It fetches your previous solution commit message from GitHub API (e.g., “Time: 44 ms (100%), Space: 73 MB (100%) – LeetHub”)
Automatic Upload : Creates a Solution.md file in the same folder as your code solution with the identical commit message

The result? Your GitHub repository now contains both your code solutions AND your detailed explanations, creating a complete documentation of your problem-solving approach.

Technical Challenges and Solutions

Building this feature presented several fascinating technical challenges that pushed the boundaries of Chrome extension development:

Challenge 1: Request Interception in Modern Web Applications

The Problem : LeetCode uses GraphQL requests for solution posting, but traditional content script approaches couldn’t reliably intercept these requests due to Chrome’s security model and timing issues.

The Solution : We implemented a dual content script architecture using Chrome Extension Manifest V3’s world: "MAIN" feature:


// manifest.json
"content_scripts": [
  {
    "js": ["src/js/interceptor.js"],
    "run_at": "document_start",
    "world": "MAIN" // Runs in page's JavaScript context
  },
  {
    "js": ["src/js/leetcode.js"],
    "run_at": "document_idle" // Runs in isolated extension context
  }
]

This approach allows the interceptor to catch network requests in the same execution context as LeetCode’s JavaScript while maintaining secure communication with the main extension logic.

Challenge 2: Content Security Policy Restrictions

The Problem : LeetCode’s strict Content Security Policy blocked our initial attempts to inject interceptor code directly into the page.

The Solution : Instead of inline script injection, we created a separate interceptor file that runs in the MAIN world context, bypassing CSP restrictions while maintaining functionality:


// Intercept both fetch and XMLHttpRequest methods
const originalFetch = window.fetch;
window.fetch = function(...args) {
  // Intercept and process GraphQL requests
  if (body.operationName === 'ugcArticlePublishSolution') {
    // Extract and forward solution data
  }
  return originalFetch.apply(this, args);
};

Challenge 3: Problem Name Mapping and GitHub Integration

The Problem : LeetCode’s problem slugs (e.g., “maximum-matching-of-players-with-trainers”) needed to be mapped to GitHub folder names (e.g., “2410-maximum-matching-of-players-with-trainers”), and we needed to maintain commit message consistency.

The Solution : We implemented intelligent problem name matching and GitHub API integration:


async function getLastCommitMessage(problemName) {
  // Fetch commit history from GitHub API
  const commitsUrl = `https://api.github.com/repos/${hook}/commits?path=${folderPath}`;

  // Find the most recent solution commit (skip README/NOTES)
  for (const commit of commits) {
    if (commit.message.includes('Time:') && commit.message.includes('Space:')) {
      return commit.message; // Use the same format
    }
  }
}

Challenge 4: User Experience and Settings Integration

The Problem : The feature needed to be discoverable and controllable without disrupting existing LeetHub workflows.

The Solution : We added a collapsible settings section in the extension popup with a toggle switch (enabled by default), maintaining consistency with LeetHub’s existing UI patterns.

The Result

The feature now works flawlessly, automatically creating comprehensive documentation in users’ GitHub repositories. Here’s what a typical problem folder looks like after the enhancement:


/2410-maximum-matching-of-players-with-trainers/
├── README.md # Problem description
├── 2410-maximum-matching-of-players-with-trainers.ts # Solution code  
└── Solution.md # Solution explanation ✨ NEW!

Both the code and solution post files share the same commit message format, creating a cohesive development history.

Support This Feature

I’m thrilled to contribute this feature back to the LeetCode community! The implementation is now live as a pull request in the official LeetHub-3.0 repository.

👍 If you’d find this feature useful, please show your support by giving a thumbs up to the PR: https://github.com/raphaelheinz/LeetHub-3.0/pull/69

Your support helps demonstrate community interest and encourages the maintainers to merge this enhancement, making it available to thousands of LeetCode enthusiasts worldwide.

This feature transforms LeetHub from a simple code backup tool into a comprehensive documentation system that captures both your solutions and the thought processes behind them. It’s a small change that makes a big difference in how we showcase our problem-solving journey on GitHub.

Ready to supercharge your LeetCode documentation workflow? Check out the PR and let’s make this feature a reality for everyone! 🚀

The post Building an Automated LeetCode Solution Post Sync Feature for LeetHub appeared first on Richard Fu.

Solving Starfield Perspective Distortion in 3D Space: A Three.js Case Study

Richard Fu — Mon, 28 Jul 2025 08:25:33 +0000

When building a 3D space simulation with Three.js WebGPU, I encountered a challenging visual problem that many 3D developers face: perspective distortion of billboard sprites. Here’s how I identified the issue and implemented an elegant solution.

The Problem: Stretched Stars Behind the Camera

In my Earth simulation game, I implemented a starfield background using 15,000 instanced plane geometries positioned on a sphere around the camera. The stars looked perfect when viewed straight-on, but had severe distortion issues:

Stars behind the camera appeared as vertical lines (stretched 2-3x in height)
Brightness varied dramatically based on viewing angle
Shape inconsistency made the starfield look unrealistic

Understanding the Root Cause

The distortion occurred due to perspective projection foreshortening :


// Original problematic approach
const radius = 40 + Math.random() * 20; // Stars too close to camera
const position = new THREE.Vector3(
  radius * Math.sin(phi) * Math.cos(theta),
  radius * Math.sin(phi) * Math.sin(theta), 
  radius * Math.cos(phi)
);

// Static plane orientation - doesn't face camera
const quaternion = new THREE.Quaternion(); // Identity rotation
matrix.compose(position, quaternion, scale);

Why this failed:

Close proximity (40-60 units) amplified perspective effects
Fixed orientation meant planes viewed at oblique angles appeared stretched
Perspective projection caused extreme foreshortening near camera edges

Attempted Solutions

Solution 1: Increase Distance


// Attempt 1: Move stars further away
const radius = 200 + Math.random() * 100;

Result: Stars disappeared beyond the camera’s far clipping plane (100 units).

Solution 2: Shader-Based Billboarding


// Attempt 2: TSL billboarding (complex, error-prone)
const viewDirection = normalize(cameraPosition.sub(instancePosition));
const right = normalize(cross(viewDirection, vec3(0, 1, 0)));
const up = cross(right, viewDirection);

Result: Complex TSL syntax caused shader compilation errors in WebGPU.

Solution 3: CPU Billboarding


// Attempt 3: Per-frame matrix updates (expensive)
for (let i = 0; i < starCount; i++) {
  const lookMatrix = new THREE.Matrix4();
  lookMatrix.lookAt(position, camera.position, camera.up);
  // Update 15,000 matrices per frame
}

Result: 15,000 matrix calculations per frame caused performance issues.

The Elegant Solution: Dual-Hemisphere Architecture

The final solution involved architectural redesign rather than complex workarounds:

Implementation


export class Background {
  private frontStarfield!: THREE.InstancedMesh;
  private backStarfield!: THREE.InstancedMesh;
  private starGroup!: THREE.Group;

  createStarfield(): THREE.Group {
    this.starGroup = new THREE.Group();

    // Split into two hemispheres
    this.frontStarfield = this.createStarPlane(7500, true); // Front
    this.backStarfield = this.createStarPlane(7500, false); // Back

    this.starGroup.add(this.frontStarfield);
    this.starGroup.add(this.backStarfield);

    return this.starGroup;
  }

  private createStarPlane(starCount: number, isFront: boolean): THREE.InstancedMesh {
    // Generate hemisphere positions
    for (let i = 0; i < starCount; i++) {
      const phi = Math.acos(2 * Math.random() - 1);
      const theta = Math.random() * Math.PI * 2;

      // Separate front/back hemispheres
      let z = Math.cos(phi);
      if (!isFront) z = -z;

      const distance = 50; // Fixed distance eliminates perspective issues
      position.set(
        distance * Math.sin(phi) * Math.cos(theta),
        distance * Math.sin(phi) * Math.sin(theta),
        distance * z
      );

      // Calculate proper billboard rotation
      const lookDirection = new THREE.Vector3()
        .subVectors(new THREE.Vector3(0, 0, 0), position)
        .normalize();

      // Create rotation matrix to face camera
      const up = new THREE.Vector3(0, 1, 0);
      const right = new THREE.Vector3().crossVectors(up, lookDirection).normalize();
      up.crossVectors(lookDirection, right);

      const rotMatrix = new THREE.Matrix4();
      rotMatrix.makeBasis(right, up, lookDirection);
      rotMatrix.decompose(new THREE.Vector3(), quaternion, new THREE.Vector3());

      matrix.compose(position, quaternion, scale);
    }
  }
}

Key Advantages

Fixed Distance : All stars at consistent 50-unit distance eliminates perspective distortion
Proper Billboarding : Each star’s rotation matrix calculated to face camera origin
Hemisphere Separation : Dedicated handling for front/back visibility
Performance : One-time calculation during initialization, not per-frame

Technical Benefits

Visual Quality

Consistent appearance across all viewing angles
No shape distortion regardless of camera position
Uniform brightness independent of perspective

Performance

Zero runtime cost for billboard calculations
GPU-optimized instanced rendering for 15,000 stars
Scalable to even larger star counts

Maintainability

Simple architecture easier to debug and extend
Clear separation between front/back star management
Reusable pattern for other billboard sprite scenarios

Enhanced Features

The solution also enabled advanced visual effects:


// TSL-based twinkling with individual star timing
const sparkle = sin(mul(timeUniform, sparkleSpeedUniform)
  .add(mul(randomAttr, float(6.28))))
  .mul(float(0.5)).add(float(0.5));

const pulse = sin(mul(timeUniform, pulseSpeedUniform)
  .add(pulsePhase))
  .mul(float(0.4)).add(float(0.6));

// Sharp-edged circular stars
const circularAlpha = smoothstep(float(0.5), float(0.2), distance);
const finalAlpha = mul(circularAlpha, mul(sparkleEnhanced, pulse));

Features achieved:

Individual star twinkling with unique timing per star
GPU-parallelized effects for 15,000 stars with zero performance cost
Realistic sparkle and pulse effects mimicking atmospheric scintillation
Sharp-edged circular stars with configurable falloff

Performance Metrics

The final implementation delivers excellent performance:

15,000 stars rendering at 60+ FPS
Zero CPU overhead for star animation (GPU-only)
Minimal memory footprint using instanced rendering
WebGPU optimized with Three.js TSL shaders

Lessons Learned

Architectural solutions often outperform technical workarounds
Fixed-distance billboards eliminate many perspective issues
Hemisphere separation provides better control than sphere-based approaches
GPU shader effects can be simpler than CPU-based alternatives
WebGPU + TSL requires different approaches than traditional WebGL

Common Pitfalls to Avoid

Camera Clipping Issues


// ![❌](https://s.w.org/images/core/emoji/15.1.0/72x72/274c.png) Bad: Stars beyond far plane
const camera = new THREE.PerspectiveCamera(25, aspect, 0.1, 100);
const starDistance = 200; // Beyond far plane!

// ![✅](https://s.w.org/images/core/emoji/15.1.0/72x72/2705.png) Good: Stars within camera range
const camera = new THREE.PerspectiveCamera(25, aspect, 0.1, 100);
const starDistance = 50; // Well within range

TSL Shader Compatibility


// ![❌](https://s.w.org/images/core/emoji/15.1.0/72x72/274c.png) Bad: onBeforeCompile doesn't work with WebGPU
material.onBeforeCompile = (shader) => {
  // This won't execute in WebGPU mode
};

// ![✅](https://s.w.org/images/core/emoji/15.1.0/72x72/2705.png) Good: Use TSL node system
const sparkle = sin(mul(timeUniform, speedUniform));
material.opacityNode = sparkle;

Performance Anti-Patterns


// ![❌](https://s.w.org/images/core/emoji/15.1.0/72x72/274c.png) Bad: Per-frame matrix updates
animate() {
  for (let i = 0; i < 15000; i++) {
    updateStarMatrix(i); // 15k calculations per frame
  }
}

// ![✅](https://s.w.org/images/core/emoji/15.1.0/72x72/2705.png) Good: One-time setup with GPU animation
createStars() {
  // Calculate matrices once
  material.opacityNode = gpuAnimationNode; // GPU handles animation
}

Conclusion

Instead of fighting perspective projection with complex mathematical solutions, restructuring the problem space proved more effective. The dual-hemisphere approach provides perfect visual results while maintaining excellent performance and code clarity.

This pattern can be applied to any 3D scenario requiring consistent billboard sprite appearance across all viewing angles – from particle systems to UI elements in 3D space.

Key takeaways:

Question architectural assumptions when facing visual artifacts
GPU-based solutions often outperform CPU workarounds
WebGPU + TSL requires rethinking traditional Three.js patterns
Fixed-distance billboards solve many perspective distortion issues

Related Resources

The post Solving Starfield Perspective Distortion in 3D Space: A Three.js Case Study appeared first on Richard Fu.

Efficient Lazy Loading in Svelte: A Practical Guide for Svelte 4 and Svelte 5 (Runes)

Richard Fu — Mon, 28 Jul 2025 02:51:34 +0000

Modern web applications are growing in complexity and size, often including many components that are not needed on the initial page load. Lazy loading is a powerful technique to optimize bundle size and improve performance by loading components only when they are actually needed—such as widgets, modals, or rarely-used UI elements. In this post, we’ll explore how to implement lazy loading in Svelte, compare the syntax between Svelte 4 and Svelte 5 (runes mode), and discuss the benefits and potential drawbacks of this approach.

Why Lazy Load Components?

Performance: By splitting your bundle and loading code only when required, you reduce the initial load time and memory usage.
User Experience: Faster initial load means a snappier experience, especially on mobile devices or slow networks.
Scalability: As your app grows, lazy loading keeps it maintainable and modular, making it easier to manage and extend.

Svelte 4 Syntax

In Svelte 4, dynamic imports are combined with the <svelte:component> tag for lazy loading:


{#await import('./MyWidget.svelte') then Widget}
  <svelte:component this={Widget.default} someProp={value} />
{/await}

<svelte:component> allows you to render a component dynamically.
Props are passed as usual.

Svelte 5 (Runes) Syntax

Svelte 5 introduces runes and direct component invocation, but for lazy loading, the recommended approach is to use the imported component as a tag inside an {#await} block:


{#await import('./MyWidget.svelte') then Widget}
  <Widget.default someProp={value} />
{/await}

This is the idiomatic way for lazy loading in Svelte 5.
Direct invocation (Widget.default({ someProp: value })) is for advanced use cases, not markup.

Dynamic Import in a Loop

You can dynamically load a component inside an {#each} loop, which is useful for rendering lists of widgets or cards:


{#each items as item}
  {#await import('./MyWidget.svelte') then Widget}
    <Widget.default data={item} />
  {/await}
{/each}

Performance Note:

Svelte will only import the module once, even if the loop has many items. Subsequent imports use the cached module, so there is no repeated network or disk load.
The only overhead is rendering multiple component instances, which is normal for any list rendering.

Drawbacks and Considerations

Initial Delay: The first time a component is loaded, there may be a slight delay as the code is fetched and parsed. For critical UI, consider preloading or keeping it in the main bundle.
SSR Compatibility: Lazy loading is primarily a client-side optimization. If you use server-side rendering, ensure your approach is compatible or fallback gracefully.
Code Splitting: Too many small chunks can increase HTTP requests. Group related components when possible.
State Management: If your lazy-loaded component depends on global state, ensure the state is available when the component mounts.

Conclusion

Lazy loading components in Svelte is a simple yet effective way to optimize your app’s performance and scalability. By leveraging dynamic imports and Svelte’s template syntax, you can keep your initial bundle small and load features only when needed. Both Svelte 4 and Svelte 5 support this pattern, with Svelte 5 offering a more streamlined syntax.

References:

The post Efficient Lazy Loading in Svelte: A Practical Guide for Svelte 4 and Svelte 5 (Runes) appeared first on Richard Fu.