RendererFactory API Reference

The RendererFactory provides a centralized API for creating and managing Three.js WebGPU renderers in Hyperscape. Location: packages/shared/src/utils/rendering/RendererFactory.ts

Overview

As of commit 47782ed (2026-02-27), Hyperscape only supports WebGPU. All WebGL fallback code has been removed.

Breaking Changes

UniversalRenderer type removed (always WebGPURenderer)
RendererBackend type now only accepts "webgpu"
All WebGL detection methods removed
WebGL fallback flags ignored

API

createRenderer

Creates a WebGPU renderer instance.

static createRenderer(
  canvas: HTMLCanvasElement,
  options?: {
    antialias?: boolean;
    alpha?: boolean;
    powerPreference?: 'high-performance' | 'low-power' | 'default';
  }
): WebGPURenderer

Parameters:

canvas - HTMLCanvasElement to render to
options - Optional renderer configuration
- antialias - Enable antialiasing (default: true)
- alpha - Enable alpha channel (default: false)
- powerPreference - GPU power preference (default: 'high-performance')

Returns: WebGPURenderer instance Throws: Error if WebGPU is not available Example:

import { RendererFactory } from '@hyperscape/shared';

const canvas = document.getElementById('game-canvas') as HTMLCanvasElement;
const renderer = RendererFactory.createRenderer(canvas, {
  antialias: true,
  powerPreference: 'high-performance',
});

// Renderer is always WebGPURenderer
renderer.setSize(window.innerWidth, window.innerHeight);
renderer.setPixelRatio(window.devicePixelRatio);

getBackend

Returns the current renderer backend (always "webgpu").

static getBackend(): 'webgpu'

Returns: "webgpu" (string literal) Example:

const backend = RendererFactory.getBackend();
console.log(backend); // "webgpu"

Error Handling

WebGPU Not Available

If WebGPU is not available, createRenderer throws an error:

try {
  const renderer = RendererFactory.createRenderer(canvas);
} catch (error) {
  console.error('WebGPU not available:', error);
  // Show error message to user
  showWebGPUError();
}

Recommended Error Handling

import { RendererFactory } from '@hyperscape/shared';

function initializeRenderer(canvas: HTMLCanvasElement) {
  // Check WebGPU support before creating renderer
  if (!navigator.gpu) {
    throw new Error(
      'WebGPU is not supported in this browser. ' +
      'Please use Chrome 113+, Edge 113+, or Safari 18+ (macOS 15+).'
    );
  }

  try {
    return RendererFactory.createRenderer(canvas);
  } catch (error) {
    console.error('Failed to create WebGPU renderer:', error);
    throw new Error(
      'Failed to initialize WebGPU. Please check:\n' +
      '1. Browser version (Chrome 113+, Edge 113+, Safari 18+)\n' +
      '2. Hardware acceleration enabled\n' +
      '3. GPU drivers up to date\n' +
      '4. Visit webgpureport.org for compatibility check'
    );
  }
}

Migration from WebGL

Before (WebGL Fallback)

// ❌ OLD CODE - No longer works
import { RendererFactory } from '@hyperscape/shared';

const renderer = RendererFactory.createRenderer(canvas);
// Type: UniversalRenderer (WebGLRenderer | WebGPURenderer)

if (RendererFactory.isWebGLFallbackForced()) {
  console.log('Using WebGL fallback');
}

After (WebGPU Only)

// ✅ NEW CODE - WebGPU only
import { RendererFactory } from '@hyperscape/shared';

const renderer = RendererFactory.createRenderer(canvas);
// Type: WebGPURenderer (always)

// No fallback checks needed - WebGPU is required

Type Definitions

import type { WebGPURenderer } from 'three/webgpu';

// Renderer backend (always 'webgpu')
type RendererBackend = 'webgpu';

// Renderer options
interface RendererOptions {
  antialias?: boolean;
  alpha?: boolean;
  powerPreference?: 'high-performance' | 'low-power' | 'default';
}

// RendererFactory class
class RendererFactory {
  static createRenderer(
    canvas: HTMLCanvasElement,
    options?: RendererOptions
  ): WebGPURenderer;
  
  static getBackend(): 'webgpu';
}

docs/migration/webgpu-only.md - WebGPU migration guide
CLAUDE.md - WebGPU requirements and troubleshooting
AGENTS.md - AI assistant WebGPU guidelines

Browser Compatibility

Browser	Minimum Version	WebGPU Support	Notes
Chrome	113+	✅ Full	Recommended
Edge	113+	✅ Full	Chromium-based
Safari	18+	✅ Full	Requires macOS 15+
Firefox	Nightly	⚠️ Partial	Behind flag, not recommended
Opera	99+	✅ Full	Chromium-based
Brave	1.52+	✅ Full	Chromium-based

Check compatibility at webgpureport.org.

Performance Considerations

GPU Selection

WebGPU automatically selects the best available GPU:

// Request high-performance GPU
const renderer = RendererFactory.createRenderer(canvas, {
  powerPreference: 'high-performance',
});

Memory Management

WebGPU uses GPU memory more efficiently than WebGL:

Shared buffers: Geometry and textures shared across instances
Automatic cleanup: GPU resources freed when renderer is destroyed
Memory limits: Respects GPU memory limits (no overallocation)

Render Pipeline

WebGPU uses a modern render pipeline:

Compute shaders: For particle systems, grass, terrain
Storage buffers: For large datasets (vegetation, NPCs)
Indirect rendering: For instanced meshes (trees, rocks)

Examples

Basic Setup

import { RendererFactory } from '@hyperscape/shared';
import { Scene, PerspectiveCamera } from 'three';

const canvas = document.getElementById('game-canvas') as HTMLCanvasElement;
const renderer = RendererFactory.createRenderer(canvas);

const scene = new Scene();
const camera = new PerspectiveCamera(75, window.innerWidth / window.innerHeight);

function animate() {
  requestAnimationFrame(animate);
  renderer.render(scene, camera);
}

animate();

With Error Handling

import { RendererFactory } from '@hyperscape/shared';

function setupRenderer(canvas: HTMLCanvasElement) {
  if (!navigator.gpu) {
    showError('WebGPU not supported. Please use Chrome 113+, Edge 113+, or Safari 18+.');
    return null;
  }

  try {
    const renderer = RendererFactory.createRenderer(canvas, {
      antialias: true,
      powerPreference: 'high-performance',
    });
    
    renderer.setSize(window.innerWidth, window.innerHeight);
    renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
    
    return renderer;
  } catch (error) {
    console.error('WebGPU initialization failed:', error);
    showError('Failed to initialize WebGPU. Please check your GPU drivers and browser settings.');
    return null;
  }
}

Cleanup

function cleanup(renderer: WebGPURenderer) {
  // Dispose renderer resources
  renderer.dispose();
  
  // Clear canvas
  const canvas = renderer.domElement;
  const context = canvas.getContext('webgpu');
  if (context) {
    context.unconfigure();
  }
}

Configuration

Operations

Renderer factory

RendererFactory API Reference

Overview

Breaking Changes

API

createRenderer

getBackend

Error Handling

WebGPU Not Available

Recommended Error Handling

Migration from WebGL

Before (WebGL Fallback)

After (WebGPU Only)

Type Definitions

Browser Compatibility

Performance Considerations

GPU Selection

Memory Management

Render Pipeline

Examples

Basic Setup

With Error Handling

Cleanup

​RendererFactory API Reference

​Overview

​Breaking Changes

​API

​createRenderer

​getBackend

​Error Handling

​WebGPU Not Available

​Recommended Error Handling

​Migration from WebGL

​Before (WebGL Fallback)

​After (WebGPU Only)

​Type Definitions

​Related Documentation

​Browser Compatibility

​Performance Considerations

​GPU Selection

​Memory Management

​Render Pipeline

​Examples

​Basic Setup

​With Error Handling

​Cleanup

RendererFactory API Reference

Overview

Breaking Changes

API

createRenderer

getBackend

Error Handling

WebGPU Not Available

Recommended Error Handling

Migration from WebGL

Before (WebGL Fallback)

After (WebGPU Only)

Type Definitions

Related Documentation

Browser Compatibility

Performance Considerations

GPU Selection

Memory Management

Render Pipeline

Examples

Basic Setup

With Error Handling

Cleanup