Three.js Composition Patterns

Integrate Helios with Three.js to drive 3D animations frame-by-frame. This ensures deterministic rendering and perfect synchronization.

Quick Start (React Three Fiber)

The key is to disable the R3F internal loop (frameloop="never") and drive the scene update manually via the advance() method in a Helios subscription.

1. Setup Component

import React, { useState, useEffect } from 'react';
import { Canvas } from '@react-three/fiber';
import { Helios } from '@helios-project/core';

// Singleton Helios instance
const helios = new Helios({
  fps: 30,
  duration: 10,
  width: 1920,
  height: 1080
});

if (typeof window !== 'undefined') {
    window.helios = helios; // Expose for Player/Renderer
}

export default function App() {
  const [r3fState, setR3fState] = useState(null);

  useEffect(() => {
    if (!r3fState) return;

    // Subscribe to Helios ticks
    const unsubscribe = helios.subscribe((state) => {
      // Calculate time in seconds
      const timeInSeconds = state.currentFrame / state.fps;

      // Manually advance R3F state
      // This updates the clock and renders the scene
      r3fState.advance(timeInSeconds);
    });

    return unsubscribe;
  }, [r3fState]);

  return (
    <Canvas
      frameloop="never" // Disable automatic loop
      onCreated={(state) => setR3fState(state)} // Capture R3F state
      gl={{ antialias: true }}
    >
      <Scene />
    </Canvas>
  );
}

2. Scene Component

Use useFrame as usual, but it will only fire when advance() is called.

import { useRef } from 'react';
import { useFrame } from '@react-three/fiber';

function Scene() {
  const meshRef = useRef();

  useFrame((state, delta) => {
    // state.clock.elapsedTime is now synced with Helios
    const time = state.clock.elapsedTime;

    if (meshRef.current) {
        meshRef.current.rotation.x = time;
        meshRef.current.rotation.y = time * 0.5;
    }
  });

  return (
    <mesh ref={meshRef}>
      <boxGeometry />
      <meshStandardMaterial color="orange" />
    </mesh>
  );
}

Quick Start (Vanilla Three.js)

For vanilla Three.js, you simply call renderer.render() inside the Helios subscription.

import * as THREE from 'three';
import { Helios } from '@helios-project/core';

// Setup Helios
const helios = new Helios({ duration: 5, fps: 30 });
window.helios = helios;

// Setup Three.js
const canvas = document.getElementById('canvas');
const renderer = new THREE.WebGLRenderer({ canvas });
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, 1920 / 1080, 0.1, 1000);
const cube = new THREE.Mesh(new THREE.BoxGeometry(), new THREE.MeshBasicMaterial({ color: 0x00ff00 }));
scene.add(cube);

// Animation Loop
helios.subscribe((state) => {
  const time = state.currentFrame / state.fps;

  // Update logic
  cube.rotation.x = time;
  cube.rotation.y = time;

  // Render
  renderer.render(scene, camera);
});

Optimization Tips

• Antialiasing: Enable it in WebGLRenderer or <Canvas> for better quality, but be aware of performance cost.
• Shadows: If using shadows, ensure they update correctly. In frameloop="never", you might need to mark shadows as needing update if they are static.
• GLTF Loading: Use waitUntilStable or ensure assets are loaded before rendering starts. Helios waits for window.load by default in 'dom' mode, but 'canvas' mode relies on the canvas being ready.

Source Files

• Example: examples/react-three-fiber/
• Example: examples/threejs-canvas-animation/