Character Builder

Character Builder

The CharacterBuilder provides a fluent API for creating character configurations with sensible defaults and type safety.

Basic Usage

import { CharacterBuilder } from 'react-3rd-person-character';
 
const characterConfig = new CharacterBuilder({ fps: 60 })
  .withName('Player')
  .withCameraSettings({ radius: 5 })
  .withMovement({ movementSpeed: 5 })
  .with3DModels('/models/player', PlayerModel, Scenario3D)
  .build();

Configuration Options

Core Settings

fps (required)

The frame rate for physics and animation updates.

new CharacterBuilder({ fps: 60 })

Camera Settings

radius

Distance from the character to the camera.

.withCameraSettings({ 
  radius: 5,           // Default: 5
  cameraOffsetY: 2,    // Default: 2
  cameraOffsetZ: 0     // Default: 0
})

Velocity Settings

Configure physics simulation parameters:

.withVelocity({
  defaultVelocitySimulatorMass: 1,      // Default: 1
  defaultVelocitySimulatorDamping: 0.8, // Default: 0.8
  defaultRotationSimulatorMass: 1,      // Default: 1
  defaultRotationSimulatorDamping: 0.8, // Default: 0.8
  mass: 1                               // Default: 1
})

Movement Settings

Configure character movement behavior:

.withMovement({
  movementSpeed: 5,    // Default: 5
  boostSpeed: 8,       // Default: 8
  jumpForce: 10        // Default: 10
})

3D Models

Configure the character and scenario models:

.with3DModels(
  modelPath,           // Path to model files
  PlayerModel,         // React component for character
  Scenario3D,          // React component for environment
  null,                // Optional: loading component
  [1, 2, 1]           // Optional: model scale [x, y, z]
)

Complete Example

const characterConfig = new CharacterBuilder({ fps: 60 })
  .withName('Adventure Hero')
  .withCameraSettings({
    radius: 6,
    cameraOffsetY: 3,
    cameraOffsetZ: 1
  })
  .withVelocity({
    defaultVelocitySimulatorMass: 1.2,
    defaultVelocitySimulatorDamping: 0.7,
    defaultRotationSimulatorMass: 1.2,
    defaultRotationSimulatorDamping: 0.7,
    mass: 1.5
  })
  .withMovement({
    movementSpeed: 6,
    boostSpeed: 10,
    jumpForce: 12
  })
  .with3DModels(
    '/models/hero',
    HeroModel,
    ForestScenario,
    LoadingSpinner,
    [1.2, 1.2, 1.2]
  )
  .build();

TypeScript Support

The CharacterBuilder provides full TypeScript support with proper type inference:

import { CharacterConfig } from 'react-3rd-person-character';
 
// The builder returns a properly typed configuration
const config: CharacterConfig = new CharacterBuilder({ fps: 60 })
  .withName('Player')
  .build();

Validation

The builder includes built-in validation to ensure all required properties are set:

// This will throw an error if required properties are missing
const config = new CharacterBuilder({ fps: 60 })
  .withName('Player')
  .build(); // Error: Missing required 3D models configuration

Best Practices

  1. Set FPS First: Always set the fps in the constructor
  2. Use Descriptive Names: Give your characters meaningful names
  3. Test Physics Settings: Adjust velocity and movement settings based on your game feel
  4. Optimize Models: Use appropriate model scales and loading components
  5. Mobile Considerations: Test camera settings on mobile devices
Getting StartedComponents