r3f-ecs-integration

R3F ECS Integration

When to Use

Use this skill when:

• Building complex games with R3F and ECS
• Managing many game entities efficiently
• Separating data (ECS) from presentation (React)
• Optimizing React Three Fiber performance
• Creating data-driven game architectures

Core Principles

1. ECS for Logic: Use ECS for game state and systems
2. React for Rendering: Use R3F components for 3D presentation
3. Unidirectional Flow: ECS → React, not React → ECS
4. Minimal Re-renders: Update ECS data without triggering React
5. Sync Strategy: Batch updates from ECS to React

Implementation

1. ECS React Context

// contexts/ECSContext.tsx
import React, { createContext, useContext, useEffect, useRef } from 'react';
import { World } from '../ecs/World';
import { EntityManager } from '../ecs/EntityManager';
import { ComponentManager } from '../ecs/ComponentManager';

interface ECSContextValue {
  world: World;
  entityManager: EntityManager;
  componentManager: ComponentManager;
}

const ECSContext = createContext<ECSContextValue | null>(null);

export function ECSProvider({ children }: { children: React.ReactNode }) {
  const worldRef = useRef<World>();

  if (!worldRef.current) {
    worldRef.current = new World();
  }

  useEffect(() => {
    return () => {
      worldRef.current?.clear();
    };
  }, []);

  const value: ECSContextValue = {
    world: worldRef.current,
    entityManager: worldRef.current.getEntityManager(),
    componentManager: worldRef.current.getComponentManager(),
  };

  return <ECSContext.Provider value={value}>{children}</ECSContext.Provider>;
}

export function useECS(): ECSContextValue {
  const context = useContext(ECSContext);
  if (!context) {
    throw new Error('useECS must be used within ECSProvider');
  }
  return context;
}

export function useWorld(): World {
  return useECS().world;
}

2. ECS-Driven Rendering

// components/EntityRenderer.tsx
import { useEffect, useState } from 'react';
import { useFrame } from '@react-three/fiber';
import { useECS } from '../contexts/ECSContext';
import { Transform, Renderable } from '../ecs/components';
import { EntityId } from '../ecs/types';

interface EntityRendererProps {
  entity: EntityId;
}

export function EntityRenderer({ entity }: EntityRendererProps) {
  const { componentManager } = useECS();
  const [, forceUpdate] = useState({});

  // Get components
  const transform = componentManager.get(entity, Transform);
  const renderable = componentManager.get(entity, Renderable);

  if (!transform || !renderable || !renderable.visible) {
    return null;
  }

  // Update mesh position from transform component
  useFrame(() => {
    if (renderable.mesh) {
      renderable.mesh.position.set(transform.x, transform.y, transform.z);
      renderable.mesh.rotation.y = transform.rotation;
      renderable.mesh.scale.setScalar(transform.scale);
    }
  });

  return <primitive object={renderable.mesh} />;
}