miniplex

While <ECS.Entity> is useful for one-off entities (like a Player), you should use imperative code (e.g., ECS.world.add()) for high-frequency or bulk entity management (like enemies or projectiles). Design your React components to react to these changes via <Entities> or useEntities rather than using React to manage the entire lifecycle of every entity.

// 1. Define imperative logic in a module
export const spawnEnemy = () =>
  ECS.world.add({
    position: { x: 0, y: 0, z: 0 },
    velocity: { x: 0, y: 0, z: 0 },
    health: 100,
    enemy: true
  })

// 2. Use React to react to those changes
export const Enemies = () => (
  <ECS.Entities in={ECS.world.with("enemy")}>
    <ECS.Component name="three">
      <EnemyShipModel />
    </ECS.Component>
  </ECS.Entities>
)

Miniplex does not provide a built-in system scheduler. Instead, you implement systems by using your existing framework's loop (e.g., useFrame from @react-three/fiber) to iterate over entities matching a specific query.

import { useFrame } from "@react-three/fiber"
import { ECS } from "./state"

const movingEntities = ECS.world.with("position", "velocity")

const MovementSystem = () => {
  useFrame((_, dt) => {
    for (const entity of movingEntities) {
      entity.position.x += entity.velocity.x * dt
      entity.position.y += entity.velocity.y * dt
      entity.position.z += entity.velocity.z * dt
    }
  })

  return null
}

The core pattern for using miniplex-react is to create a React API object from an existing Miniplex World. It is recommended to do this in a dedicated module (e.g., state.ts) and export the resulting object so it can be imported throughout your application.

createReactAPI automatically inherits the entity type from your World, providing full TypeScript support for all components and hooks.

/* state.ts */
import { World } from "miniplex"
import createReactAPI from "miniplex-react"

/* Our entity type */
export type Entity = {
  /* ... */
}

/* Create a Miniplex world that holds our entities */
const world = new World<Entity>()

/* Create and export React bindings */
export const ECS = createReactAPI(world)

To use miniplex-react, you must also install its peer dependency miniplex. Use your preferred package manager to add both to your project.

npm install miniplex miniplex-react
yarn add miniplex miniplex-react
pnpm add miniplex miniplex-react

The object returned by createReactAPI contains a world property. This allows you to interact with the ECS world imperatively (adding, modifying, or destroying entities) using the standard Miniplex API.

const entity = ECS.world.add({ position: { x: 0, y: 0 } })

If a component is designed to store rich objects (like Three.js objects) and provides a React ref, you can pass a single React child to <ECS.Component>. The component's ref value will be automatically captured and stored as the component's data in the ECS world.

import { ECS } from "./state"

const Player = () => (
  <ECS.Entity>
    <ECS.Component name="position" data={{ x: 0, y: 0, z: 0 }} />
    <ECS.Component name="health" data={100} />
    <ECS.Component name="three">
      <mesh>
        <sphereGeometry />
        <meshStandardMaterial color="hotpink" />
      </mesh>
    </ECS.Component>
  </ECS.Entity>
)

The useEntities hook allows a component to subscribe to a Miniplex query or world. The component will automatically re-render whenever entities are added to or removed from the selection. This is useful for implementing side effects that depend on the presence of specific entities.

const cameraTargets = ECS.world.with("cameraTarget", "object3d")

const MyCamera = () => {
  const camera = useRef<PerspectiveCamera>()
  const [cameraTarget] = useEntities(cameraTargets)

  useEffect(() => {
    if (!camera.current || !cameraTarget) return
    camera.current.lookAt(cameraTarget.object3d.position)
  }, [cameraTarget])

  return <PerspectiveCamera ref={camera} makeDefault />
}

When composing entities using nested components, you can use the useCurrentEntity hook to retrieve the entity represented by the nearest <ECS.Entity> ancestor in the React tree.

const Health = () => {
  const entity = ECS.useCurrentEntity()

  useEffect(() => {
    /* Do something with the entity */
  }, [entity])

  return null
}

Both <ECS.Entity> and <ECS.Entities> support children render props. Instead of JSX children, you can pass a function that receives the entity as its first argument. This is useful for accessing entity data during the render loop or performing per-entity logic (like randomization).

const enemies = ECS.world.with("enemy")

const EnemyShips = () => (
  <ECS.Entities in={enemies}>
    {(entity) => {
      const health = Math.random() * 1000
      return (
        <ECS.Entity entity={entity}>
          <ECS.Component name="health" data={health} />
          <ECS.Component name="three">
            <EnemyShipModel />
          </ECS.Component>
        </ECS.Entity>
      )
    }}
  </ECS.Entities>
)

You can use <ECS.Entity> to represent an entity that was already created elsewhere (e.g., via imperative code). This allows you to 'enhance' that entity by attaching additional components via React.

Note: Unlike a standard <ECS.Entity>, an entity passed via the entity prop will not be destroyed when the component unmounts.

const RenderPlayer = ({ player }) => (
  <ECS.Entity entity={player}>
    <ECS.Component name="three">
      <mesh>
        <sphereGeometry />
        <meshStandardMaterial color="hotpink" />
      </mesh>
    </ECS.Component>
  </ECS.Entity>
)

Use <ECS.Entity> to declare a new entity and <ECS.Component> to attach data to it.

Lifecycle: When an <ECS.Entity> component mounts, it creates the entity in the world. When it unmounts, it automatically destroys the entity.

import { ECS } from "./state"

const Player = () => (
  <ECS.Entity>
    <ECS.Component name="position" data={{ x: 0, y: 0, z: 0 }} />
    <ECS.Component name="health" data={100} />
  </ECS.Entity>
)