React 3rd Person Character

A fast, minimal library designed to simplify the implementation of third-person interactive characters in 3D web scenes, using the latest ecosystem of 3D libraries for React.

Docs

Official Documentation

Demo

Live CodeSandbox Demo
More examples will be added soon.

What This Library Solves

Managing compatibility across physics engines, three.js, and React-specific 3D libraries can be painful and time-consuming.

This library abstracts and integrates:

• react-three-fiber
• @react-three/drei
• @react-three/rapier
• three
• xstate (for character state management)

You do not need to install or manage these dependencies manually. The library re-exports all required modules.

📦 Packages Provided

This package exports:

• All required 3D packages as FIBER, DREI, RAPIER, and THREE
• A state machine-driven character provider with mobile and desktop control rendering
• A modular setup that allows flexible 3D scene integration

⚠️ Important Notes

This library is non-opinionated. You are free to compose your scenes and behaviors however you like. That said, due to current technical limitations, one-shot animation delays must be specified manually — they cannot be extracted at runtime.

const character = new CharacterBuilder({ fps: 60 })
  .withAnimatedActionDelays({
    elevate: staticDelayTimeForelevate,
    action1: staticDelayTimeForaction1,
    action2: staticDelayTimeForaction2,
    action3: staticDelayTimeForaction3,
    action4: staticDelayTimeForaction4,
  })
  .build();

In future versions, we aim to provide an architectural solution to infer animation lengths automatically.

If you're unsure about your clip durations, you can inspect them manually:

action.getClip().duration; // returns a number in seconds

Refer to three.js documentation on AnimationAction for more details.

Usage Example

Entry Point and ActorProvider

import {
  ActorProvider,
  FIBER,
  StyledMobileControls,
  ExperienceWrapper,
  THREE,
} from "react-3rd-person-character";

import Experience from "./experience/index.tsx";
import { character } from "./experience/config.ts";
import { useDevice } from "use-device-react";

const gl: FIBER.GLProps = {
  outputColorSpace: THREE.SRGBColorSpace,
  toneMapping: THREE.ACESFilmicToneMapping,
  toneMappingExposure: 1.0,
};

export default function App() {
  const { isDesktop } = useDevice();
  return (
    <ActorProvider
      character={character}
      physics={{ debug: false }}
      renderControls
    >
      <FIBER.Canvas gl={gl} shadows>
        <ExperienceWrapper>
          <Experience />
        </ExperienceWrapper>
      </FIBER.Canvas>
      {!isDesktop && <StyledMobileControls />}
    </ActorProvider>
  );
}

Player implementaiton

import { DREI, Player, RAPIER, Scenario } from "react-3rd-person-character";

const Experience = () => {
  return (
    <>
      {/* any Three.js element or custom 3D components */}
      <RAPIER.RigidBody type="fixed" colliders="trimesh">
        <Scenario />
      </RAPIER.RigidBody>

      <Player>
        <RAPIER.CuboidCollider
          position={[0, 0.1, 0]}
          args={[0.2, 0.12, 0.2]}
        />
      </Player>
    </>
  );
};

export default Experience;

Contributing (Coming Soon)

This library is currently in an early stage of development. Once a more stable version is released, the GitHub repository will be made public and open to community contributions.

If you're interested in collaborating, feel free to reach out in advance or keep an eye out for the public release.

We plan to welcome:

• Feature requests
• Bug reports
• Pull requests (for core, examples, or docs)
• Architecture suggestions

Your input will help shape a more flexible and production-ready third-person character system for the modern React 3D ecosystem.# react-3rd-person-character