Forem: Raw Fun Gaming

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.

Keeping iframes Running When Hidden: A Journey Through Browser Optimizations

Richard Fu — Fri, 20 Jun 2025 03:49:18 +0000

The Challenge

Have you ever needed to keep an iframe running even when it’s “hidden” from view? This seemingly simple requirement can become surprisingly complex due to browser optimizations. In our case, we needed to maintain active game states in minimized casino widgets without affecting performance or user experience.

Failed Approaches

1. CSS Visibility and Display Properties

Our first attempt used basic CSS properties to hide the iframes:


.minimized-iframe {
  visibility: hidden;
  display: none;
}

This immediately failed as browsers aggressively optimize hidden content, often suspending JavaScript execution and resource loading in hidden iframes.

2. Opacity and Pointer Events

Next, we tried making the iframe invisible while keeping it in the DOM:


.minimized-iframe {
  opacity: 0;
  pointer-events: none;
}

While this seemed promising, browsers still optimized away the “invisible” content, causing our iframe content to freeze.

3. CSS Clip and Transform

We then attempted to keep a tiny portion visible using clipping and scaling:


.minimized-iframe {
  clip-path: polygon(0 0, 1px 0, 1px 1px, 0 1px);
  transform: scale(0.01);
  position: fixed;
  top: 0;
  left: 0;
}

This worked inconsistently across browsers, and the transform sometimes triggered the same optimization behaviors we were trying to avoid.

The Working Solution: Layer Management

The solution that finally worked was counterintuitive: instead of trying to hide the iframe, we kept it fully rendered but visually concealed behind a background-matching overlay.

Here’s a simplified example:


<div class="background-overlay"></div>
<div class="iframe-container minimized">
  <iframe src="game.html"></iframe>
</div>



.iframe-container.minimized {
  position: fixed;
  z-index: -999; /* Behind overlay, but above page background */
  /* Center in viewport */
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
}

.background-overlay {
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  bottom: 0;
  z-index: -998; /* Above iframe, below regular content */
  background-color: var(--page-background-color);
  pointer-events: none;
}

Why This Works

No Browser Optimization Triggers
- The iframe remains fully rendered and active
- No visibility, opacity, or display properties that might trigger browser optimizations
- Transform is only used for positioning, not scaling
Visual Concealment
- The overlay matches the page background color
- Positioned between the iframe and regular content
- Pointer events disabled to prevent interaction
Performance Considerations
- Minimal DOM manipulation
- No constant state monitoring needed
- Hardware acceleration can still be utilized

Key Learnings

Browser optimizations, while generally beneficial, can work against specific use cases
Visual hiding ≠ functional hiding
Sometimes the best solution isn’t about hiding content but managing how it’s layered
Working with browser behaviors rather than against them leads to more robust solutions

Caveats and Considerations

Ensure your z-index management is consistent across the application
Consider memory usage since content remains fully rendered
Test across different browsers and devices
Consider fallback strategies for older browsers

Conclusion

This solution might seem counterintuitive – after all, we’re not really “hiding” the content, just putting it behind something else. However, it proves to be more reliable than fighting browser optimizations. Sometimes, the best solution isn’t about using more sophisticated techniques, but rather understanding and working with browser behaviors.

Remember: browsers are optimized for common use cases. When you need to handle edge cases, you might need to think outside the box – or in this case, think in layers rather than visibility states.

This solution was discovered while working on a complex web application that required maintaining active states in minimized iframes. Special thanks to browser optimization algorithms for making this problem interesting enough to write about!

The post Keeping iframes Running When Hidden: A Journey Through Browser Optimizations appeared first on Richard Fu.

Optimizing Rendering with PixiJS v8: A Deep Dive into the New Culling API

Richard Fu — Thu, 24 Apr 2025 11:10:16 +0000

The culling feature has been available as an extension in earlier versions of PixiJS, but with the release of PixiJS v8, it is now officially integrated into the core. This motivated us to revisit the feature and explore how to take advantage of it. However, the current documentation and examples are still limited. In this article, I’ll walk through how culling works in PixiJS v8, highlight some nuances, and share my personal insights on its usage.

Understanding the Intuition

In our project, we often render a long list of UI items, which are masked with a rectangular shape. Performance tends to degrade when rendering 500+ items, especially on lower-end devices. Currently, we manually set .visible = false for any object outside the visible screen. We wanted to explore if culling could help us automate this process efficiently.

First Look at PixiJS v8 Culling

Both the v8 Migration Guide and Performance Tips mention the new culling API, but they lack detailed usage examples. Most tutorials online still reference older versions. Fortunately, the Culler test script proved to be an invaluable resource in understanding how the feature is intended to work.

From the migration guide, here’s a basic usage example:


const container = new Container();
const view = new Rectangle(0, 0, 800, 600);

container.cullable = true;
container.cullArea = new Rectangle(0, 0, 400, 400);
container.cullableChildren = false;

app.stage.addChild(container);

Culler.shared.cull(container, view);

Defining the Cull View

The view should be defined as a Rectangle using global coordinates relative to the canvas.
If the canvas size is dynamic (e.g., responsive layout), you should update the view accordingly and invoke Culler.shared.cull() again. For example:


let timeSinceLoad = 0;
app.ticker.add(function (ticker) {
  timeSinceLoad += ticker.deltaMS;
  view = new Rectangle(
    app.renderer.width / 2 - 100,
    app.renderer.height / 2 - 100,
    200 + timeSinceLoad * 0.1,
    200 + timeSinceLoad * 0.1
  );
  Culler.shared.cull(container, view, false);
});

In most cases, you can use app.stage and app.screen directly as inputs for culling. This works well in a game loop or render tick:


app.ticker.add(() => {
  Culler.shared.cull(app.stage, app.screen);
});

Understanding Cull Area

The cullArea property can be confusing. It’s critical to note that this rectangle is defined in global coordinates, and does not inherit transformations like position or rotation from the container it’s attached to. This can lead to unexpected behavior, as seen in one of the official test cases:


const view = { x: 0, y: 0, width: 100, height: 100 };

it('cullable container with cullArea should not be rendered if the bounds do not intersect the frame', () =>
{
    const container = new Container();
    const graphics = container.addChild(new Graphics().rect(0, 0, 10, 10).fill());

    container.cullable = true;
    container.cullArea = new Rectangle(-10, -10, 10, 10);
    container.x = container.y = 107.08;
    container.rotation = Math.PI / 4;

    Culler.shared.cull(container, view, false);

    expect(container.culled).toBe(true);
    expect(graphics.culled).toBe(false);
});

Even though the container and its child graphics are visually inside the view, the cullArea (defined in global space) is outside the view. As a result, the container is culled, but its graphics child is not.

Although graphics.culled is false here, it is not rendered because its parent container has been culled.

In practice, I find it rare to define a custom cullArea that doesn’t align with the container’s own bounds. However, there may be edge cases—like complex layering or shared masks—where this flexibility becomes useful.

Conclusion

While the built-in culling system in PixiJS v8 simplifies object visibility in static or fixed-size canvases, it adds a bit of complexity when dealing with responsive layouts or dynamically changing viewports. You must ensure that the view and cull areas are accurately maintained in global space.

In our case, sticking with manual masking combined with setting .visible = false based on Y-position checks remains the most straightforward and performant approach for large lists of items:

if (y < -object.height / 2 || y > screen.height + object.height / 2) object.visible = false;

That said, Pixi’s new culling API is a powerful addition—especially for dynamic scenes—and it’s worth exploring to see if it fits your rendering optimization needs.

The post Optimizing Rendering with PixiJS v8: A Deep Dive into the New Culling API appeared first on Richard Fu.

Building a Slack Bot for Board Game Nights with TypeScript and GitHub Actions

Richard Fu — Thu, 17 Apr 2025 15:50:29 +0000

As a software engineer and board game enthusiast, I wanted to solve a common problem in our office: organizing our weekly board game nights. While we had a regular schedule (Friday afternoons), we needed a better way to:

Remind people about the upcoming session
Suggest games to play
Get quick feedback on game preferences

This led me to create a Slack bot that would handle these tasks automatically. In this post, I’ll share my journey of building this bot using TypeScript, Slack’s Web API, and GitHub Actions.

The Initial Idea

Every Friday at 4:30 PM, our team gathers for board games. We have quite a collection – from strategic games like Catan to party games like The Resistance. The challenge was getting everyone on the same page about:

Which games to bring
Who’s interested in playing
What time to meet

I wanted a bot that would:

Send fun, casual reminders
Randomly suggest a few games from our collection
Let people vote on games using emoji reactions
Run completely automatically

Technical Stack

After considering various options, I settled on:

TypeScript : For type safety and better development experience
Slack Web API : For sending messages and handling reactions
GitHub Actions : For scheduling and running the bot
Node.js : For the runtime environment

Key Features

1. Dynamic Message Generation

Instead of sending the same boring message every week, I created a pool of casual, fun messages:


{
  "messages": [
    "Heads up, nerds! It's board game Friday tomorrow 🃏 – 4:30pm at L9!",
    "Warning: Friday fun incoming! Join us 4:30pm tomorrow at L9 🎲",
    "Don't make weekend plans – we roll dice tomorrow, 4:30pm L9 😉"
  ]
}

2. Game Configuration

Each game is configured with its name, Slack emoji name, and player count requirements:


{
  "games": [
    {
      "name": "Catan",
      "emoji": "rice", // Slack emoji name for reactions
      "emojiUnicode": "🌾", // Unicode emoji for reference
      "minPlayers": 3,
      "maxPlayers": 4
    },
    {
      "name": "Carcassonne",
      "emoji": "european_castle", // Slack emoji name for reactions
      "emojiUnicode": "🏰", // Unicode emoji for reference
      "minPlayers": 2,
      "maxPlayers": 5
    }
  ]
}

Note : For emojis, we use Slack emoji names (without colons) instead of Unicode emojis. This ensures compatibility with Slack’s reaction system. For example, use “rice” instead of 🌾, “european_castle” instead of 🏰. You can find available emoji names in your Slack workspace by typing : in the message input. The emojiUnicode field is included for reference only and is not used by the bot.

3. Emoji Reactions

The bot automatically adds emoji reactions for each suggested game, making it easy for people to indicate their preferences:

Development Process

1. Setting Up the Project

I started with a basic Node.js project and added TypeScript:


npm init
npm install typescript @types/node --save-dev
npm install @slack/web-api dotenv

2. Configuring Slack

The bot requires several Slack permissions:

chat:write: For sending messages
channels:read: For accessing channels
reactions:write: For adding emoji reactions

3. Environment Configuration

I separated the configuration into:

.env: For sensitive data (Slack token)
config.json: For game list and channel settings (production)
config.test.json: For testing configuration (separate channel and settings)

This separation allows us to:

Keep sensitive data out of version control
Test new features safely in a separate channel
Easily switch between production and test environments

4. Implementing the Core Logic

The main functionality is in src/board-game-reminder.ts:

Load configurations
Pick random games
Send message with game suggestions
Add emoji reactions

5. Setting Up CI/CD

I used GitHub Actions for:

Continuous Integration (testing and building)
Scheduled execution (weekly reminders)
Automated deployments

Testing and Iteration

I created a separate test channel (social-board-games-testing) to:

Test message formatting
Verify emoji reactions
Check scheduling
Debug any issues

This proved invaluable for iterating on the bot’s functionality without spamming the main channel.

Deployment and Automation

The bot runs entirely on GitHub Actions, requiring:

A GitHub repository
Slack Bot Token (stored in GitHub Secrets)
Scheduled workflow (runs every Thursday)

Results and Impact

The bot has successfully:

Increased participation in game nights
Made game selection more democratic
Reduced coordination overhead
Added a fun element to our weekly reminders

Future Improvements

Some ideas for future enhancements:

RSVP functionality
Game history tracking
Player count optimization
Integration with game rules/tutorials

Try It Yourself

The project is open source and available on GitHub. To set up your own instance:

Fork the repository: git clone https://github.com/furic/board-game-slack-reminder.git
Create a Slack app and get your bot token
Configure your environment:
- Add your Slack token
- Customize the game list
- Set your channel name
Deploy and enjoy automated game night coordination!

Development with Cursor AI

One of the interesting aspects of this project was my experience using Cursor AI as a development partner. What impressed me most was how the AI assistant helped navigate through some tricky implementation details:

Intelligent API Understanding

I was particularly surprised by how Cursor AI understood the Slack API requirements. When implementing emoji reactions, it correctly identified that we needed to use Slack’s emoji format (e.g., “rice” instead of “🌾”) rather than Unicode emojis. This saved me from potential runtime issues and demonstrated the AI’s practical knowledge of API specifications.

Step-by-Step Problem Solving

The development process with Cursor AI was methodical and educational:

Initial Implementation : We started with Unicode emojis in the configuration files, which seemed logical at first.
Problem Identification : When testing the bot, we encountered invalid_name errors with emoji reactions. Cursor AI quickly identified that Slack’s API requires emoji names rather than Unicode characters.
Systematic Updates : The AI guided me through updating multiple files:
- Changed emoji format in config.json and config.test.json
- Updated documentation in README.md
- Added clear examples and explanations in this blog
Testing and Verification : After each change, the AI suggested running tests to verify the fixes, showing a practical understanding of development workflows.

Configuration Management

The AI helped establish a robust configuration system:


// Before: Using Unicode emojis
{
  "name": "Catan",
  "emoji": "🌾", // This caused issues with Slack's API
}

// After: Using Slack emoji names with Unicode reference
{
  "name": "Catan",
  "emoji": "rice", // This works correctly with Slack reactions
  "emojiUnicode": "🌾", // Kept for reference
}

Documentation Focus

What stood out was the AI’s insistence on maintaining clear documentation. It made sure to:

Add explanatory notes about emoji usage
Include practical examples
Document the reasoning behind technical decisions
Keep configuration files in sync

This experience showed how AI can be a valuable development partner, not just for writing code but for maintaining best practices and documentation throughout the development process.

Conclusion

Building this bot was a fun way to solve a real problem while learning about:

Slack’s API capabilities
TypeScript development
GitHub Actions automation
Configuration management

The source code is available on GitHub, and I welcome contributions and suggestions for improvements!

The post Building a Slack Bot for Board Game Nights with TypeScript and GitHub Actions appeared first on Richard Fu.

Flappy Spaceship – Exploring the Frontiers of Pixi-React v8 Beta

Richard Fu — Tue, 01 Oct 2024 01:44:48 +0000

I built a re-skinned version of the classic Flappy Bird game called Flappy Spaceship , with a space theme, using Pixi-React v8 beta. The goal was to explore Pixi-React as a game engine without adding new game mechanics.

What I Built

Fl a ppy Spaceship is a space-themed reimagining of the classic Flappy Bird game. While retaining the original game’s mechanics, this version gives it a fresh space adventure vibe. Additionally, it serves as a platform to experiment with Pixi-React v8 beta, which is still in development.

This project was submitted to Dev.to’s Web Game Challenge, Build a Game: Alien Edition.

Inspired by and translated from the original Flappy Bird Game (Vue3 and PixiJS). I ported the codebase to React and leveraged the Pixi-React library to showcase its capabilities.

Live Demo

You can try it out here: Live Demo. Use mouse clicks or the spacebar to play.

Journey

Here are some key things I learned and encountered while building this game:

Motivation: In my day-to-day work, I use Pixi v7 with Svelte, but I was eager to explore Pixi v8 and Pixi-React, especially since Pixi-React is still in beta. This project was the perfect opportunity to dive into it.
Setting up the project from scratch: npx create-vite@latest --template react-ts flappy-spaceship cd flappy-spaceship npm i pixi.js@8 @pixi/react@beta
Translation from Vue to React: There’s a great Pixi Flappy Bird project written in Vue, which I’m not very familiar with. With help from ChatGPT, I translated the code into React. However, since Pixi-React is in beta, I encountered issues where ChatGPT didn’t have the latest info, requiring me to debug certain problems on my own.
Button interaction issue: I wanted to use Pixi-UI’s FancyButton, but found that the callback functionality doesn’t yet work in Pixi-React. I asked about this in a discussion thread, but haven’t received a reply yet. As a workaround, I used a full-screen click to start the game instead.
Custom background: I created a simple space background inspired by Pixi’s Star Warp example, replacing the Sprite elements with basic Graphics for simplicity.
Bug encountered: I ran into a bug while using Pixi-React’s useAssets hook, where loading the same asset multiple times didn’t work. After the first time, the asset failed to load, meaning the rock piles after the first weren’t rendered. This issue seems to be tracked in this bug report. I ended up using the depreciated useAsset which is working perfectly fine.
Context API limitations: Initially, I wanted to manage screen dimensions using React’s createContext, but later discovered that this feature isn’t fully supported in Pixi-React. I may find alternative ways later to handle screen size changes.

TODO

Add simple spaceship animation
Incorporate sound effects and background music
Implement high score saving and loading
Add a wormhole mechanic to advance the player over a set distance
Introduce floating quantum cores as an in-game currency
Create a shop where players can buy new spaceship skins

Conclusion

While Pixi-React is still in beta and presents some challenges with newer features, it offers significant potential. Some Pixi packages, like Pixi-UI , may need updates to function properly in this environment. Hopefully, future releases of Pixi-React will include more detailed documentation and address some of these early-stage issues.

Feel free to explore the source code and license in the GitHub repository.

The post Flappy Spaceship – Exploring the Frontiers of Pixi-React v8 Beta appeared first on Richard Fu.

Pixi’s Asset Pack 1.0: A Step Forward for Asset Management

Richard Fu — Mon, 30 Sep 2024 08:11:23 +0000

Pixi’s Asset Pack has officially reached version 1.0, and after diving deep into it, I can confidently say that it shows a lot of promise for our projects. However, there are still some issues that need ironing out. In this post, I’ll walk you through how it works, the benefits it offers, and a few limitations we’ve encountered.

Why Use Pixi’s Asset Pack?

Here are some key features that make Asset Pack a valuable addition to your development toolkit:

Texture Sprite Packing: No more manual work with Texture Packer.
Automated Compression & File Formats: Keeps a 100% source texture while automatically generating compressed Png and WebP versions.
Mipmaps Generation: Ensures devices with lower resolutions use smaller textures, improving performance and reducing game size.
Bundle Manifest Generation: No more hard-coded asset lists.
Hash Versioning: Ensures you always load the latest files.
Artist-Friendly Workflow : Artists only need to manage raw assets, while the tool handles export automation.

Current Issues

While Asset Pack is promising, there are a few issues we’ve encountered:

Spine Atlas Export : Spine atlas is not correctly exported (submitted a PR for spine-runtime).
Bitmap Font Export : Bitmap fonts aren’t exporting properly (submitted an issue).
Sound Sprite Support : Currently unsupported (submitted an issue).

How to Set Up Asset Pack

Setting up Asset Pack is straightforward. Begin by installing it with this commend:


npm install --save-dev @assetpack/core

Next, create an .assetpack.js file with the following content:


import { pixiPipes } from '@assetpack/core/pixi';

export default {
    entry: './raw-assets',
    output: './public/assets',
    pipes: [
        ...pixiPipes({
            resolutions: { high: 3, default: 2, low: 1 },
            manifest: {
                trimExtensions: true
            },
            texturePacker: { texturePacker: { removeFileExtension: true }},
        }),
    ],
};

The pixiPipes function creates a default configuration that works in most cases. Here’s a breakdown of what my preferred settings do:

resolutions: Specifies three resolutions (high, default, low). I will explain more about this later.
manifest:trimExtensions: Removes texture file extensions in the manifest for easier reference in your code.
texturePacker:texturePacker:trimExtensions: Removes texture file extensions in the spritesheet Json when packing textures, again for easier reference.

Next, create a folder called raw-assets in your project root. Each folder inside raw-assets will represent a bundle, and you can specify it with a {m} tag. For our project, I created the following bundles:

game-screen{m}: Contains all game assets and starts loading after the loading screen is shown.
load-screen{m}: Assets used in the loading screen. These are unloaded once the screen is hidden to save memory.
shared{m}: Assets used by both the loading screen and the game.
ui{m} : UI assets, separated for easier management (though they can be put in the game-screen folder).

Based on asset type, structure the folders like this:

Single Sprite : Place textures in any file path. Reference them by filename (without extension), e.g., background. If there are two files with the same name, reference them with the relative path.

Sprite Sheet (Texture Packer): Put textures in a folder with a {tps} tag. Sprite sheet Json files will be generated, and you can access the texture array by folder name, e.g., skins.

Spine : Place the Atlas, Json, and texture files in a folder. Access the spine data and atlas with their filenames (without extension). If your Atlas and Json share the same filename, you’ll need to use extensions, e.g., character.json and character.atlas.

Finally, run the CLI command:


npm assetpack

This packs everything into the public folder and generates a manifest.json containing all file references. You can also set up a GitHub workflow to automate this process.

How to Use Packed Assets

Now, let’s look at the code to load the packed assets:


import { type AssetsManifest, Assets } from '@pixi/assets';
import type { Spritesheet } from '@pixi/spritesheet';
import * as utils from '@pixi/utils';
import { Sprite } from '@pixi/sprite';
import { Spine } from '@esotericsoftware/spine-pixi';

(async () => {
    const baseUrl = './public/assets';
    // const baseUrl = 'https://s3/my-bucket';

    const response = await fetch(baseUrl + '/manifest.json');
    const manifest = (await response.json()) as AssetsManifest;
    if (!manifest.bundles) {
        throw new Error('[Assets] Invalid assets manifest');
    }

    const resolution = Math.min(utils.isMobile.any ? window.devicePixelRatio : 3, 3);

    await Assets.init({
        basePath: baseUrl,
        manifest,
        texturePreference: { resolution: [resolution, 1], format: ['webp', 'png'] },
    });

    await Assets.loadBundle('shared');
    await Assets.loadBundle('load-screen');

    // load-screen assets loaded, show load screen

    await Assets.loadBundle('ui');
    await Assets.loadBundle('game-screen', onProgress); // onProgress to feed the progress bar

    // game assets loaded, wait for player to hide load screen

    Assets.unloadBundle('load-screen');

    const singleSprite = Sprite.from('background');

    const spriteSheet = Assets.cache.get<Spritesheet>('skins');
    const spriteSheetSprite = new Sprite(spriteSheet.textures['hat.png']);

    const spine = Spine.from('character-skel', 'character');
})();

This code loads assets using the manifest and adjusts resolution preferences based on device pixel density. Here are the key steps:

File Location : Set baseUrl as a local or server folder path.
Resolution Handling : Set the preferred resolution (3x, 2x, 1x) based on devicePixelRatio.
Asset Loading: Use Assets.loadBundle() to load asset bundles defined in the manifest.
Unload Bundles: Once the loading screen is no longer needed, unload its assets with Assets.unloadBundle().
Accessing Assets: Use Sprite.from() for single sprites, Assets.cache.get() for spritesheets, and Spine.from() for Spine animations.

Conclusion

While Pixi’s Asset Pack is still evolving, it offers a solid foundation for managing assets efficiently in Pixi-based projects. I believe it has the potential to become an essential tool for many developers. Has anyone else worked with it? I’d love to hear your thoughts and experiences!

The post Pixi’s Asset Pack 1.0: A Step Forward for Asset Management appeared first on RF Game Dev Blog.