Getting Started

Getting Started

This guide will help you set up and use the React 3rd Person Character library in your project.

Installation

npm install react-3rd-person-character
# or
yarn add react-3rd-person-character
# or
pnpm add react-3rd-person-character

Basic Setup

1. Create a Character Configuration

First, create a character configuration using the CharacterBuilder:

import { CharacterBuilder } from 'react-3rd-person-character';
 
const characterConfig = new CharacterBuilder({ fps: 60 })
  .withName('Player')
  .withCameraSettings({ 
    radius: 5, 
    cameraOffsetY: 2 
  })
  .withVelocity({
    defaultVelocitySimulatorMass: 1,
    defaultVelocitySimulatorDamping: 0.8,
    defaultRotationSimulatorMass: 1,
    defaultRotationSimulatorDamping: 0.8,
    mass: 1
  })
  .withMovement({ 
    movementSpeed: 5, 
    boostSpeed: 8 
  })
  .with3DModels(
    '/models/player', 
    PlayerModel, 
    Scenario3D, 
    null, 
    [1, 2, 1]
  )
  .build();

2. Set Up Your App Component

import {
  CharacterConfigProvider,
  ExperienceWrapper,
  Player,
  Scenario,
  StyledMobileControls,
  FIBER,
  THREE,
} from "react-3rd-person-character";
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 (
    <CharacterConfigProvider character={characterConfig}>
      <FIBER.Canvas gl={gl} shadows>
        <ExperienceWrapper>
          <Scenario />
          <Player />
        </ExperienceWrapper>
      </FIBER.Canvas>
      {!isDesktop && <StyledMobileControls />}
    </CharacterConfigProvider>
  );
}

3. Create Your 3D Models

You'll need to create React components for your character and scenario models:

// PlayerModel.tsx
import { useGLTF } from '@react-three/drei';
 
export default function PlayerModel({ nodes, materials }) {
  const { scene } = useGLTF('/models/player.glb');
  
  return <primitive object={scene} />;
}
 
// Scenario3D.tsx
export default function Scenario3D() {
  return (
    <group>
      {/* Your 3D environment */}
      <mesh>
        <boxGeometry args={[10, 1, 10]} />
        <meshStandardMaterial color="green" />
      </mesh>
    </group>
  );
}

Key Components

CharacterConfigProvider

The main provider that wraps your entire 3D experience. It manages the character's state machine and provides context to all child components.

ExperienceWrapper

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

Player

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

Scenario

Renders your 3D environment. Automatically manages loading states.

StyledMobileControls

Provides touch controls for mobile devices. Only renders on non-desktop devices.

Next Steps

IntroductionCharacter Builder