WebGPU-Only Migration Guide

Breaking Change: Hyperscape now requires WebGPU. All WebGL fallback code has been removed.

What Changed

Commit 47782ed (2026-02-27)

Title: fix(rendering): enforce WebGPU-only mode, remove all WebGL fallbacks Summary: WebGPU is now REQUIRED. WebGL will NOT work. All TSL (Three Shading Language) materials require WebGPU and there is no fallback path.

Removed Code

RendererFactory.ts:

❌ isWebGLForced - Removed
❌ isWebGLFallbackForced - Removed
❌ isWebGLFallbackAllowed - Removed
❌ isWebGLAvailable() - Removed
❌ isOffscreenCanvasAvailable() - Removed
❌ canTransferCanvas() - Removed
❌ UniversalRenderer type - Removed (use WebGPURenderer)
❌ RendererBackend - Now only "webgpu" (was "webgpu" | "webgl")

stream-to-rtmp.ts:

❌ STREAM_CAPTURE_DISABLE_WEBGPU - Ignored (warning logged)
❌ forceWebGL URL parameter - Removed
❌ disableWebGPU URL parameter - Removed

deploy-vast.sh:

❌ Headless fallback mode - Removed (deployment fails if Xorg/Xvfb cannot provide WebGPU)
❌ Soft fallback to headless - Removed (explicit display accessibility verification required)

ecosystem.config.cjs:

❌ DUEL_FORCE_WEBGL_FALLBACK - Deprecated (always false)
✅ STREAM_CAPTURE_HEADLESS - Hardcoded to false (WebGPU requires display)

Why WebGPU-Only?

Technical Reasons

TSL Shaders: All materials use Three.js Shading Language (TSL)
- TSL only works with WebGPU node material pipeline
- No WebGL equivalent exists
Post-Processing: Bloom, tone mapping, color grading use TSL
- WebGPU-only node materials
- Cannot be ported to WebGL
Performance: WebGPU provides better performance
- Compute shaders for vegetation, terrain, particles
- Instanced rendering optimizations
- Better memory management

Root Cause of Streaming Issues

The headless fallback in deploy-vast.sh was silently falling back to a mode that doesn’t support WebGPU when Xorg/Xvfb setup failed. This caused:

Black frames (no rendering)
Browser hangs (WebGPU initialization timeout)
Silent failures (no error messages)

Fix: Deployment now FAILS if WebGPU cannot be initialized. No soft fallbacks.

Migration Steps

For Developers

Update browser:
- Chrome 113+ (recommended)
- Edge 113+
- Safari 18+ (macOS 15+) - Safari 17 support removed
- Check: webgpureport.org
Enable hardware acceleration:
- Chrome: 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

Remove WebGL code:

// ❌ REMOVE
if (isWebGLRenderer(renderer)) { ... }

// ✅ REPLACE WITH
// WebGPU is always available - no checks needed

Update renderer creation:

// ❌ OLD
const renderer = await createRenderer({ backend: 'webgpu' });

// ✅ NEW
const renderer = await createRenderer(); // Always WebGPU

Remove fallback flags:

// ❌ REMOVE
const url = `${baseUrl}?forceWebGL=true`;
const url = `${baseUrl}?disableWebGPU=true`;

// ✅ REPLACE WITH
const url = baseUrl; // WebGPU is always enabled

For Deployment (Vast.ai)

Verify GPU requirements:
- NVIDIA GPU with Vulkan support
- Check: nvidia-smi and vulkaninfo --summary
Ensure display server:
- Xorg (preferred) or Xvfb (fallback)
- NOT headless mode
- Verify: xdpyinfo -display $DISPLAY

Update environment variables:

# ❌ REMOVE
STREAM_CAPTURE_DISABLE_WEBGPU=true
DUEL_FORCE_WEBGL_FALLBACK=true

# ✅ ADD/UPDATE
STREAM_CAPTURE_HEADLESS=false  # Always false
DUEL_CAPTURE_USE_XVFB=false    # Set by deploy script
GPU_RENDERING_MODE=xorg        # Set by deploy script

Run deployment script:
```
./scripts/deploy-vast.sh
```
Script will:
- Detect GPU and display capabilities
- Configure Xorg or Xvfb
- Verify WebGPU initialization
- FAIL if WebGPU cannot be initialized

Monitor deployment:

pm2 logs hyperscape-duel --lines 200

# Look for:
# ✅ "WebGPU preflight PASSED"
# ✅ "GPU Diagnostics: WebGPU Status: Hardware accelerated"
# ❌ "WebGPU preflight FAILED"
# ❌ "WebGPU may not be working properly"

For CI/CD

Update GitHub Secrets:
- Remove any FORCE_WEBGL or DISABLE_WEBGPU secrets
- Ensure VAST_HOST, VAST_PORT, VAST_SSH_KEY are set
Update workflows:
- .github/workflows/deploy-vast.yml already updated
- No changes needed if using latest workflow
Verify deployment:
- Check GitHub Actions logs for WebGPU preflight test
- Verify GPU diagnostics in deployment output

Breaking Changes

API Changes

RendererFactory:

// ❌ REMOVED
type RendererBackend = "webgpu" | "webgl";
type UniversalRenderer = WebGPURenderer | WebGLRenderer;
function isWebGLAvailable(): Promise<boolean>;
function isWebGLRenderer(renderer): boolean;

// ✅ NEW
type RendererBackend = "webgpu";
type WebGPURenderer = InstanceType<typeof THREE.WebGPURenderer>;
// No WebGL detection functions

Exports:

// ❌ REMOVED from index.ts and index.client.ts
export { isWebGLAvailable, isWebGLRenderer, UniversalRenderer };

// ✅ KEPT
export { WebGPURenderer, createRenderer, isWebGPUAvailable };

Environment Variables

Deprecated (ignored with warning):

STREAM_CAPTURE_DISABLE_WEBGPU - Logs warning, WebGPU always enabled
DUEL_FORCE_WEBGL_FALLBACK - Deprecated, always false

Removed:

forceWebGL URL parameter
disableWebGPU URL parameter

Required:

STREAM_CAPTURE_HEADLESS=false - WebGPU requires display
DUEL_CAPTURE_USE_XVFB - Set by deploy script (true for Xvfb, false for Xorg)
GPU_RENDERING_MODE - Set by deploy script (xorg, xvfb-vulkan, ozone-headless)

Deployment Changes

deploy-vast.sh:

❌ Removed headless fallback (line ~200)
✅ Added explicit WebGPU validation
✅ Added GPU diagnostics extraction
✅ Added WebGPU preflight test
✅ Deployment FAILS if WebGPU cannot initialize

ecosystem.config.cjs:

❌ Removed DUEL_FORCE_WEBGL_FALLBACK=true
✅ Added STREAM_CAPTURE_HEADLESS=false (hardcoded)
✅ Added STREAM_CAPTURE_DISABLE_WEBGPU=false (diagnostic only)

Compatibility

Supported Browsers

Browser	Minimum Version	Notes
Chrome	113+	✅ Recommended
Edge	113+	✅ Recommended
Safari	18+ (macOS 15+)	⚠️ Safari 17 support removed
Firefox	121+	⚠️ Behind flag, not recommended

Unsupported Environments

❌ WebGL-only browsers (IE, old Safari)
❌ Headless Chrome without GPU
❌ Software rendering (SwiftShader, llvmpipe)
❌ Containers without GPU access
❌ WebViews that block WebGPU

Rollback

If you need to rollback to WebGL support:

Revert to commit before 47782ed:

git checkout 1b2e230  # Last commit before WebGL removal

Note: This is NOT recommended
- WebGL support was broken (TSL shaders don’t work)
- Streaming was producing black frames
- No active maintenance of WebGL code path
Better solution: Fix WebGPU availability
- Update browser
- Update GPU drivers
- Enable hardware acceleration
- Use supported deployment environment

Testing

Verify WebGPU Support

Browser:

// Open browser console
const adapter = await navigator.gpu?.requestAdapter();
console.log('WebGPU available:', adapter !== null);

Automated:

# Run WebGPU preflight test
bun run packages/server/scripts/stream-to-rtmp.ts

# Look for:
# ✅ "WebGPU preflight PASSED"
# ❌ "WebGPU preflight FAILED"

Visual Testing

All visual tests now require WebGPU:

npm test --workspace=packages/shared

# Tests will fail if WebGPU is unavailable
# Check test logs for WebGPU initialization errors

FAQ

Q: Can I use WebGL as a fallback? A: No. TSL shaders only work with WebGPU. There is no WebGL equivalent. Q: What if my users don’t have WebGPU? A: They need to update their browser or use a supported browser. WebGPU is widely available (Chrome 113+, Edge 113+, Safari 18+). Q: Can I run Hyperscape in headless mode? A: No. WebGPU requires a display server (Xorg or Xvfb). Pure headless mode does not support WebGPU. Q: What about mobile devices? A: WebGPU is supported on iOS 18+ (Safari) and Android (Chrome 113+). Older devices are not supported. Q: Can I use software rendering? A: No. WebGPU requires hardware GPU rendering. Software renderers (SwiftShader, llvmpipe) do not support WebGPU. Q: What if deployment fails with “WebGPU preflight FAILED”? A: Check GPU access (nvidia-smi), Vulkan support (vulkaninfo), and display server (xdpyinfo). Deployment will not proceed without WebGPU.

Support

WebGPU Issues: Check webgpureport.org for browser compatibility
GPU Streaming: See AGENTS.md for Vast.ai deployment architecture
Development: See CLAUDE.md for development guidelines
Bug Reports: GitHub Issues

47782ed - Enforce WebGPU-only mode, remove all WebGL fallbacks
ff45217 - Add timeout to WebGPU initialization
d5c6884 - Add WebGPU diagnostics and preflight test
205f964 - Update WebGL references to WebGPU in client code
6fd626a - Fix model cache index buffer type preservation

Configuration

Operations

WEBGPU MIGRATION

WebGPU-Only Migration Guide

What Changed

Commit 47782ed (2026-02-27)

Removed Code

Why WebGPU-Only?

Technical Reasons

Root Cause of Streaming Issues

Migration Steps

For Developers

For Deployment (Vast.ai)

For CI/CD

Breaking Changes

API Changes

Environment Variables

Deployment Changes

Compatibility

Supported Browsers

Unsupported Environments

Rollback

Testing

Verify WebGPU Support

Visual Testing

FAQ

Support

References

Configuration

Operations

​WebGPU-Only Migration Guide

​What Changed

​Commit 47782ed (2026-02-27)

​Removed Code

​Why WebGPU-Only?

​Technical Reasons

​Root Cause of Streaming Issues

​Migration Steps

​For Developers

​For Deployment (Vast.ai)

​For CI/CD

​Breaking Changes

​API Changes

​Environment Variables

​Deployment Changes

​Compatibility

​Supported Browsers

​Unsupported Environments

​Rollback

​Testing

​Verify WebGPU Support

​Visual Testing

​FAQ

​Support

​Related Commits

​References

WebGPU-Only Migration Guide

What Changed

Commit 47782ed (2026-02-27)

Removed Code

Why WebGPU-Only?

Technical Reasons

Root Cause of Streaming Issues

Migration Steps

For Developers

For Deployment (Vast.ai)

For CI/CD

Breaking Changes

API Changes

Environment Variables

Deployment Changes

Compatibility

Supported Browsers

Unsupported Environments

Rollback

Testing

Verify WebGPU Support

Visual Testing

FAQ

Support

Related Commits

References