WebGPU Requirements - Hyperscape

CRITICAL: WebGPU Required

Hyperscape requires WebGPU. WebGL WILL NOT WORK. This is a hard requirement due to our use of TSL (Three Shading Language) for all materials and post-processing effects. TSL only works with the WebGPU node material pipeline.

BREAKING CHANGE (February 27, 2026): All WebGL fallback code has been removed in commit 47782ed. The game will not render without WebGPU support.

Why WebGPU-Only?

TSL Shaders

All materials use Three.js Shading Language (TSL) which requires WebGPU:

// Example TSL shader (from ProceduralGrass.ts)
import { MeshStandardNodeMaterial, uniform, vec3, color } from "three/webgpu";

const material = new MeshStandardNodeMaterial();
material.colorNode = color(0x4a7c3e); // TSL color node
material.roughnessNode = uniform(0.8); // TSL uniform node

TSL Features Used:

Node-based material system
GPU-computed animations (dissolve, fade, flicker)
Procedural noise and patterns
Custom vertex/fragment shaders

Post-Processing Effects

All post-processing uses TSL-based node materials:

// From PostProcessingComposer.ts
import { pass, bloom, toneMappingACES } from "three/webgpu";

const bloomPass = bloom(scene, camera);
const toneMappingPass = toneMappingACES();

Effects:

Bloom (glow effects)
Tone mapping (HDR to SDR)
Color grading (LUT-based)
Outline rendering (entity highlights)

No Fallback Path

There is NO WebGL fallback because:

TSL compiles to WGSL (WebGPU Shading Language)
WGSL cannot run on WebGL
Rewriting all shaders for WebGL would require months of work
WebGPU provides better performance and features

Browser Requirements

Supported Browsers

Browser	Minimum Version	Notes
Chrome	113+	Recommended, best performance
Edge	113+	Chromium-based, same as Chrome
Safari	18+ (macOS 15+)	Safari 17 support removed Feb 2026
Firefox	Nightly only	Behind flag, not recommended

Check your browser’s WebGPU support at webgpureport.org

Safari 17 Support Removed

BREAKING CHANGE (commit 205f96491, February 27, 2026): Safari 17 support was removed. Safari 18+ (macOS 15 Sequoia or later) is now required. Reason:

Safari 17 had incomplete WebGPU implementation
Missing features caused rendering bugs
Safari 18 provides full WebGPU support

Migration:

Update macOS to 15.0+ (Sequoia)
Update Safari to 18.0+
Or use Chrome 113+ / Edge 113+

GPU Requirements

Desktop GPUs

Minimum:

NVIDIA GTX 1060 or equivalent
AMD RX 580 or equivalent
Intel Arc A380 or equivalent

Recommended:

NVIDIA RTX 3060 or better
AMD RX 6600 or better
Intel Arc A750 or better

Mobile GPUs

iOS:

iPhone 12 or newer (A14 Bionic+)
iPad Air 4th gen or newer
iPad Pro 3rd gen or newer

Android:

Snapdragon 888 or newer
Mali-G78 or newer
Adreno 660 or newer

Mobile WebGPU support is experimental. Desktop browsers provide the best experience.

Enabling WebGPU

Chrome / Edge

WebGPU is enabled by default in Chrome 113+ and Edge 113+. Verify:

Open chrome://gpu
Check “WebGPU” status
Should show “Hardware accelerated”

If disabled:

Go to chrome://settings
System → “Use hardware acceleration when available”
Enable the toggle
Restart browser

Safari

WebGPU is enabled by default in Safari 18+ (macOS 15+). Verify:

Safari → Preferences → Advanced
Check “Show Develop menu in menu bar”
Develop → Experimental Features
Verify “WebGPU” is checked

If disabled:

Develop → Experimental Features → WebGPU
Check the box
Restart Safari

Firefox

WebGPU is behind a flag in Firefox (not recommended for production use). Enable:

Open about:config
Search for dom.webgpu.enabled
Set to true
Restart Firefox

Firefox WebGPU support is incomplete. Use Chrome or Edge for best experience.

Server/Streaming Requirements

For Vast.ai and other GPU servers running the streaming pipeline:

Hardware Requirements

GPU:

NVIDIA GPU with Vulkan support (REQUIRED)
RTX 3060 Ti or better recommended
Vulkan 1.2+ support

Display:

Must run headful with Xorg or Xvfb (NOT headless Chrome)
Chrome uses ANGLE/Vulkan backend to access WebGPU
Headless mode does NOT support WebGPU

Drivers:

NVIDIA driver 535+ recommended
Vulkan ICD installed (/usr/share/vulkan/icd.d/nvidia_icd.json)

Software Requirements

# Required packages
apt-get install -y \
  nvidia-driver-535 \
  vulkan-tools \
  mesa-vulkan-drivers \
  xvfb \
  google-chrome-unstable

# Verify installation
nvidia-smi
vulkaninfo --summary

Environment Configuration

# Display server (REQUIRED for WebGPU)
DISPLAY=:99
DUEL_CAPTURE_USE_XVFB=false  # true for Xvfb, false for Xorg

# GPU rendering mode (auto-detected by deploy script)
GPU_RENDERING_MODE=xorg  # or xvfb-vulkan

# Force NVIDIA Vulkan ICD (avoid Mesa conflicts)
VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/nvidia_icd.json

# ANGLE backend
STREAM_CAPTURE_ANGLE=vulkan

# Headless mode (MUST be false for WebGPU)
STREAM_CAPTURE_HEADLESS=false

BREAKING CHANGE: Headless mode is NOT supported. Deployment FAILS if WebGPU cannot initialize (no soft fallbacks).

Deployment Validation

The deploy-vast.sh script validates WebGPU requirements:

# From scripts/deploy-vast.sh

# 1. Verify NVIDIA GPU accessible
if ! nvidia-smi &>/dev/null; then
  echo "ERROR: NVIDIA GPU not accessible"
  exit 1
fi

# 2. Check Vulkan ICD availability
if [ ! -f /usr/share/vulkan/icd.d/nvidia_icd.json ]; then
  echo "ERROR: NVIDIA Vulkan ICD not found"
  exit 1
fi

# 3. Ensure display server running
if ! xdpyinfo -display $DISPLAY &>/dev/null; then
  echo "ERROR: Display server not accessible"
  exit 1
fi

# 4. Run WebGPU preflight test
# (handled by stream-to-rtmp.ts during browser setup)

Deployment Fails If:

NVIDIA GPU not detected
Vulkan ICD missing
Display server not running
WebGPU preflight test fails

No Soft Fallbacks:

Previous versions fell back to headless mode
Headless mode doesn’t support WebGPU
Now deployment FAILS immediately if WebGPU unavailable

Removed Features

WebGL Fallback (BREAKING)

Removed in commit 47782ed (February 27, 2026):

// ❌ REMOVED - No longer exists
class RendererFactory {
  isWebGLForced(): boolean { /* ... */ }
  isWebGLFallbackForced(): boolean { /* ... */ }
  isWebGLFallbackAllowed(): boolean { /* ... */ }
  isWebGLAvailable(): boolean { /* ... */ }
  createWebGLRenderer(): THREE.WebGLRenderer { /* ... */ }
}

// ❌ REMOVED - No longer supported
type RendererBackend = "webgpu" | "webgl";
type UniversalRenderer = THREE.WebGPURenderer | THREE.WebGLRenderer;

Now:

// ✅ WebGPU only
type RendererBackend = "webgpu";
type UniversalRenderer = THREE.WebGPURenderer;

URL Parameters (REMOVED)

// ❌ REMOVED - These parameters are now IGNORED
?forceWebGL=1
?disableWebGPU=1

Environment Variables (DEPRECATED)

# ❌ DEPRECATED - These flags are now IGNORED
STREAM_CAPTURE_DISABLE_WEBGPU=false
DUEL_FORCE_WEBGL_FALLBACK=false

Why Kept:

Backwards compatibility with old configs
Prevents deployment failures from stale env files
Logged as warnings when set

Error Messages

User-Facing Errors

When WebGPU is unavailable, users see:

Graphics error. WebGPU is required. 
Please use Chrome 113+, Edge 113+, or Safari 18+.

Error Code: SYSTEM_WEBGL_ERROR (renamed from WebGL, kept for compatibility) Location: packages/client/src/lib/errorCodes.ts

Developer Errors

When WebGPU fails during development:

// From RendererFactory.ts
if (!navigator.gpu) {
  throw new Error(
    "WebGPU not supported. " +
    "Hyperscape requires WebGPU for TSL shaders. " +
    "Please use Chrome 113+, Edge 113+, or Safari 18+."
  );
}

Migration Guide

For Developers

If you have code that checks for WebGL:

// ❌ Old code (no longer works)
if (world.graphics?.isWebGPU) {
  // WebGPU path
} else {
  // WebGL fallback
}

// ✅ New code (WebGPU only)
// No conditional needed - always WebGPU
const renderer = world.graphics.renderer; // Always WebGPURenderer

For Deployment

Update your deployment configs:

# ❌ Remove these (no longer needed)
STREAM_CAPTURE_DISABLE_WEBGPU=false
DUEL_FORCE_WEBGL_FALLBACK=false

# ✅ Add these (required for WebGPU)
STREAM_CAPTURE_HEADLESS=false
DISPLAY=:99
GPU_RENDERING_MODE=xorg
VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/nvidia_icd.json

For Users

If you see “WebGPU not supported” error:

Check browser version:
- Chrome: chrome://version (need 113+)
- Edge: edge://version (need 113+)
- Safari: Safari → About Safari (need 18+)
Update browser:
- Chrome: google.com/chrome
- Edge: microsoft.com/edge
- Safari: Update macOS to 15.0+ (Sequoia)
Enable hardware acceleration:
- Chrome/Edge: chrome://settings → System → “Use hardware acceleration”
- Safari: Preferences → Advanced → Experimental Features → WebGPU
Update GPU drivers:
- NVIDIA: nvidia.com/drivers
- AMD: amd.com/support
- Intel: intel.com/download-center

Testing WebGPU Support

Browser Console Test

Open browser console and run:

// Check if WebGPU is available
if (navigator.gpu) {
  console.log("✅ WebGPU is available");
  
  // Try to get adapter
  navigator.gpu.requestAdapter().then(adapter => {
    if (adapter) {
      console.log("✅ WebGPU adapter found:", adapter);
      
      // Try to create device
      adapter.requestDevice().then(device => {
        console.log("✅ WebGPU device created successfully");
        device.destroy();
      }).catch(err => {
        console.error("❌ Failed to create WebGPU device:", err);
      });
    } else {
      console.error("❌ No WebGPU adapter found");
    }
  }).catch(err => {
    console.error("❌ Failed to request WebGPU adapter:", err);
  });
} else {
  console.error("❌ WebGPU not available in this browser");
}

WebGPU Report

Visit webgpureport.org to see:

WebGPU availability
GPU adapter information
Supported features and limits
Browser compatibility

Common Issues

”WebGPU not supported” Error

Cause: Browser doesn’t support WebGPU Solutions:

Update browser to Chrome 113+, Edge 113+, or Safari 18+
Enable hardware acceleration in browser settings
Update GPU drivers
Check for browser extensions blocking WebGPU

Black Screen / No Rendering

Cause: WebGPU initialized but rendering failed Solutions:

Check browser console for WebGPU errors
Verify GPU drivers are up to date
Try different browser (Chrome vs Edge vs Safari)
Disable browser extensions
Clear browser cache and reload

”GPU process was unable to boot”

Cause: GPU access disabled or driver issue Solutions:

Enable hardware acceleration: chrome://settings → System
Update GPU drivers
Check for GPU blocklist: chrome://gpu → “Problems Detected”
Try --ignore-gpu-blocklist flag (development only)

Streaming Shows Black Frames

Cause: WebGPU not initializing on remote server Solutions:

Check GPU diagnostics: bunx pm2 logs hyperscape-duel --lines 500 | grep "GPU Diagnostics"
Verify display server: echo $DISPLAY && xdpyinfo
Check Vulkan: vulkaninfo --summary
Review preflight test: bunx pm2 logs hyperscape-duel | grep preflight
Ensure STREAM_CAPTURE_HEADLESS=false

Development Rules

DO NOT:

❌ Add WebGL fallback code
❌ Use --disable-webgpu flags
❌ Use forceWebGL parameters
❌ Create headless Chrome configurations without GPU/WebGPU support
❌ Suggest WebGL as an alternative

DO:

✅ Assume WebGPU availability in all renderer code
✅ Throw errors immediately if WebGPU unavailable
✅ Use TSL for all custom shaders
✅ Test on WebGPU-capable browsers only
✅ Document WebGPU requirements in user-facing docs

WebGPU Diagnostics

GPU diagnostics and preflight testing

Deployment Guide

Production deployment with GPU configuration

Troubleshooting

Common issues and solutions

Rendering Architecture

Three.js WebGPU renderer architecture

Get Started

Guides

Core Concepts

​CRITICAL: WebGPU Required

​Why WebGPU-Only?

​TSL Shaders

​Post-Processing Effects

​No Fallback Path

​Browser Requirements

​Supported Browsers

​Safari 17 Support Removed

​GPU Requirements

​Desktop GPUs

​Mobile GPUs

​Enabling WebGPU

​Chrome / Edge

​Safari

​Firefox

​Server/Streaming Requirements

​Hardware Requirements

​Software Requirements

​Environment Configuration

​Deployment Validation

​Removed Features

​WebGL Fallback (BREAKING)

​URL Parameters (REMOVED)

​Environment Variables (DEPRECATED)

​Error Messages

​User-Facing Errors

​Developer Errors

​Migration Guide

​For Developers

​For Deployment

​For Users

​Testing WebGPU Support

​Browser Console Test

​WebGPU Report

​Common Issues

​”WebGPU not supported” Error

​Black Screen / No Rendering

​”GPU process was unable to boot”

​Streaming Shows Black Frames

​Development Rules

​DO NOT:

​DO:

​Related Documentation

WebGPU Diagnostics

Deployment Guide

Troubleshooting

Rendering Architecture

CRITICAL: WebGPU Required

Why WebGPU-Only?

TSL Shaders

Post-Processing Effects

No Fallback Path

Browser Requirements

Supported Browsers

Safari 17 Support Removed

GPU Requirements

Desktop GPUs

Mobile GPUs

Enabling WebGPU

Chrome / Edge

Safari

Firefox

Server/Streaming Requirements

Hardware Requirements

Software Requirements

Environment Configuration

Deployment Validation

Removed Features

WebGL Fallback (BREAKING)

URL Parameters (REMOVED)

Environment Variables (DEPRECATED)

Error Messages

User-Facing Errors

Developer Errors

Migration Guide

For Developers

For Deployment

For Users

Testing WebGPU Support

Browser Console Test

WebGPU Report

Common Issues

”WebGPU not supported” Error

Black Screen / No Rendering

”GPU process was unable to boot”

Streaming Shows Black Frames

Development Rules

DO NOT:

DO:

Related Documentation