Components

The library provides several key components that work together to create a complete third-person character experience.

Core Components

CharacterConfigProvider

The main provider component that manages the character's state machine and provides context to all child components.

import { CharacterConfigProvider } from 'react-3rd-person-character';
 
function App() {
  return (
    <CharacterConfigProvider character={characterConfig}>
      {/* Your 3D scene components */}
    </CharacterConfigProvider>
  );
}

Props:

character: CharacterConfig - The character configuration object

ExperienceWrapper

Handles physics setup and input listening. Must be used within a FIBER.Canvas.

import { ExperienceWrapper } from 'react-3rd-person-character';
 
function Scene() {
  return (
    <ExperienceWrapper>
      <Scenario />
      <Player />
    </ExperienceWrapper>
  );
}

Player

Renders the character with physics, animations, and movement logic.

import { Player } from 'react-3rd-person-character';
 
function Scene() {
  return (
    <ExperienceWrapper>
      <Scenario />
      <Player />
    </ExperienceWrapper>
  );
}

The Player component automatically:

Sets up physics bodies
Handles character animations
Manages movement and rotation
Integrates with the camera system

Scenario

Renders your 3D environment and manages loading states.

import { Scenario } from 'react-3rd-person-character';
 
function Scene() {
  return (
    <ExperienceWrapper>
      <Scenario />
      <Player />
    </ExperienceWrapper>
  );
}

The Scenario component:

Renders the environment model
Manages loading states
Sets up physics for the environment
Triggers the experience store when loaded

Control Components

StyledMobileControls

Provides touch controls for mobile devices with a styled UI.

import { StyledMobileControls } from 'react-3rd-person-character';
 
function App() {
  const { isDesktop } = useDevice();
  
  return (
    <>
      <FIBER.Canvas>
        {/* Your 3D scene */}
      </FIBER.Canvas>
      {!isDesktop && <StyledMobileControls />}
    </>
  );
}

UnstyledMobileControls

Provides touch controls without styling for custom UI.

import { UnstyledMobileControls } from 'react-3rd-person-character';
 
function CustomControls() {
  return (
    <div className="custom-controls">
      <UnstyledMobileControls />
    </div>
  );
}

FourControls

Provides keyboard controls for desktop devices.

import { FourControls } from 'react-3rd-person-character';
 
function DesktopControls() {
  return <FourControls />;
}

Re-exported Components

The library re-exports components from the underlying 3D libraries for convenience:

FIBER Components

import { FIBER } from 'react-3rd-person-character';
 
// Re-exports from react-three-fiber
FIBER.Canvas
FIBER.useFrame
FIBER.useThree
// ... and more

THREE Objects

import { THREE } from 'react-3rd-person-character';
 
// Re-exports from three.js
THREE.Vector3
THREE.Euler
THREE.Quaternion
// ... and more

DREI Components

import { DREI } from 'react-3rd-person-character';
 
// Re-exports from @react-three/drei
DREI.useGLTF
DREI.OrbitControls
DREI.PerspectiveCamera
// ... and more

RAPIER Components

import { RAPIER } from 'react-3rd-person-character';
 
// Re-exports from @react-three/rapier
RAPIER.Physics
RAPIER.RigidBody
RAPIER.CuboidCollider
// ... and more

Component Composition

Here's how all components work together:

import {
  CharacterConfigProvider,
  ExperienceWrapper,
  Player,
  Scenario,
  StyledMobileControls,
  FIBER,
  THREE,
} from "react-3rd-person-character";
 
export default function App() {
  return (
    <CharacterConfigProvider character={characterConfig}>
      <FIBER.Canvas>
        <ExperienceWrapper>
          <Scenario />
          <Player />
        </ExperienceWrapper>
      </FIBER.Canvas>
      <StyledMobileControls />
    </CharacterConfigProvider>
  );
}

Custom Components

You can create custom components that integrate with the library's context:

import { useActorContext } from 'react-3rd-person-character';
 
function CustomUI() {
  const { characterState } = useActorContext();
  
  return (
    <div>
      <p>Character State: {characterState.value}</p>
    </div>
  );
}

Best Practices

Always wrap with CharacterConfigProvider: This provides necessary context
Use ExperienceWrapper: Required for physics and input handling
Conditional mobile controls: Only render mobile controls on non-desktop devices
Custom styling: Use UnstyledMobileControls for custom UI
Performance: Keep custom components lightweight to maintain 60fps

Character Builder Packages