Eve library

Metaverse WebGL Engine Integration

Guide

Revision 1

On this page

This document describes the unified WebGL engine adapter that now powers the metaverse surfaces. The adapter abstracts Three.js and Babylon.js initialization while guaranteeing WebGL 2.0 capability negotiation and graceful fallbacks for older hardware.

Engine Adapter Overview#

web/src/lib/webgl-engine-adapter.ts centralises all canvas bootstrapping logic. It:

  • Detects WebGL 2.0 support with automatic downgrade to WebGL 1.0 if required.
  • Creates a configured Three.js renderer and scene when engineType === 'three'.
  • Lazily loads Babylon.js when requested, returning an engine + scene handle for future Babylon-based experiences.
  • Normalises teardown through a shared dispose() method so UI surfaces can release GPU resources reliably.

Usage#

ts
import { initialize3DEngine } from '../lib/webgl-engine-adapter';

const handle = await initialize3DEngine(canvas, {
  preferredEngine: 'auto',
  preferredWebGLVersion: 2,
  antialias: true,
  alpha: false,
  powerPreference: 'high-performance',
});

if (handle.engineType === 'three') {
  const { scene, renderer } = handle;
  // customise scene, attach cameras, etc.
} else {
  const { engine, scene } = handle;
  // experimental Babylon.js pathway.
}

The adapter always records the negotiated WebGL version (handle.webglVersion) for diagnostics and debug overlays.

MetaverseCanvas Integration#

web/src/components/MetaverseCanvas.tsx now boots through the adapter:

  • New props enginePreference and preferredWebGLVersion allow runtime selection between Three.js, Babylon.js, or automatic detection.
  • Engine diagnostics (engine type + WebGL version) surface in debug mode to aid QA and hardware validation.
  • Cleanup delegates to the adapter’s dispose() routine which in turn releases renderer, scene materials, and Babylon engines when in use.
  • Spatial audio, accessibility, content browser, and avatar subsystems continue to initialise once the Three.js handle is ready; Babylon initialisation currently stops after providing the engine handle while we build out Babylon-native scenes.

Babylon.js Dependency#

The web client now ships with @babylonjs/core as a production dependency. Local development requires running npm install inside web/ to ensure the Babylon modules are available for dynamic import.

Tip: If you prefer to keep bundle sizes minimal during experimentation, set enginePreference="three" to skip Babylon runtime loading.

Testing#

Dedicated Vitest coverage (web/src/lib/__tests__/webgl-engine-adapter.test.ts) verifies:

  • WebGL 2.0 detection and manual fallback to WebGL 1.0 contexts.
  • Adapter orchestration for Three.js renderer creation with expected options.
  • Babylon.js initialisation and disposal contracts when explicitly requested.

Component tests (web/src/components/__tests__/MetaverseCanvas.test.tsx) mock the adapter to confirm UI wiring without requiring actual WebGL contexts.

Next Steps#

  • Flesh out Babylon.js scene scaffolding that mirrors existing Three.js sacred environments.
  • Extend automated QA flows to collect adapter diagnostics across supported browsers/GPUs.
  • Consider promoting detectWebGLSupport into a shared platform utility for other surfaces (e.g., meditation visualisers, audio visualisations).