Packages

The library is structured as a monorepo with separate packages for different functionalities. You can use the entire library or import specific packages as needed.

Package Structure

react-3rd-person-character/
├── packages/
│   ├── physics/     # Physics simulation and spring systems
│   ├── controls/    # Input handling and mobile controls
│   └── core/        # Main character logic and state management
└── src/             # Main library exports

Individual Packages

Physics Package

The physics package provides spring simulation systems and physics utilities.

npm install @react-3rd-person-character/physics

import { 
  SpringSimulator, 
  VectorSpringSimulator,
  RelativeSpringSimulator 
} from '@react-3rd-person-character/physics';
 
// Spring simulation for smooth movement
const velocitySimulator = new SpringSimulator(60);
velocitySimulator.setSimulationFPS(60);
velocitySimulator.setSpring(100, 10);
 
// Vector spring for 3D movement
const vectorSimulator = new VectorSpringSimulator(60);
vectorSimulator.setSimulationFPS(60);
vectorSimulator.setSpring(100, 10);
 
// Relative spring for camera positioning
const cameraSimulator = new RelativeSpringSimulator(60);
cameraSimulator.setSimulationFPS(60);
cameraSimulator.setSpring(100, 10);

Exports:

SpringSimulator - Basic spring simulation
VectorSpringSimulator - 3D vector spring simulation
RelativeSpringSimulator - Relative positioning spring
SimulationFrame - Frame data structure
SimulationFrameVector - Vector frame data

Controls Package

The controls package provides input handling and mobile control components.

npm install @react-3rd-person-character/controls

import { 
  StyledMobileControls,
  UnstyledMobileControls,
  FourControls,
  useControls,
  useTouchControls 
} from '@react-3rd-person-character/controls';
 
// Mobile controls with styling
function MobileApp() {
  return <StyledMobileControls />;
}
 
// Custom mobile controls
function CustomControls() {
  return (
    <div className="custom-ui">
      <UnstyledMobileControls />
    </div>
  );
}
 
// Desktop keyboard controls
function DesktopControls() {
  return <FourControls />;
}
 
// Custom input handling
function CustomInput() {
  const controls = useControls();
  const touchControls = useTouchControls();
  
  // Handle input events
  return null;
}

Exports:

StyledMobileControls - Styled mobile touch controls
UnstyledMobileControls - Unstyled mobile controls
FourControls - Keyboard controls for desktop
useControls - Hook for input handling
useTouchControls - Hook for touch input

Core Package

The core package contains the main character logic, state management, and builder pattern.

npm install @react-3rd-person-character/core

import { 
  CharacterBuilder,
  CharacterConfigProvider,
  ExperienceWrapper,
  Player,
  Scenario 
} from '@react-3rd-person-character/core';
 
// Build character configuration
const config = new CharacterBuilder({ fps: 60 })
  .withName('Player')
  .withCameraSettings({ radius: 5 })
  .withMovement({ movementSpeed: 5 })
  .build();
 
// Use core components
function Game() {
  return (
    <CharacterConfigProvider character={config}>
      <ExperienceWrapper>
        <Scenario />
        <Player />
      </ExperienceWrapper>
    </CharacterConfigProvider>
  );
}

Exports:

CharacterBuilder - Fluent API for character configuration
CharacterConfigProvider - Main context provider
ExperienceWrapper - Physics and input wrapper
Player - Character component
Scenario - Environment component

Using Packages Individually

Physics Only

If you only need physics simulation:

import { SpringSimulator } from '@react-3rd-person-character/physics';
 
const spring = new SpringSimulator(60);
spring.setSpring(100, 10);
 
// Use in your own components
function CustomMovement() {
  useFrame(() => {
    spring.simulate();
    // Apply spring values to your object
  });
}

Controls Only

If you only need input handling:

import { useControls } from '@react-3rd-person-character/controls';
 
function CustomCharacter() {
  const controls = useControls();
  
  useFrame(() => {
    if (controls.forward) {
      // Move forward
    }
    if (controls.backward) {
      // Move backward
    }
  });
}

Core Only

If you want to build your own character system:

import { CharacterBuilder } from '@react-3rd-person-character/core';
 
const config = new CharacterBuilder({ fps: 60 })
  .withName('CustomCharacter')
  .build();
 
// Use with your own physics and controls

Package Dependencies

physics: No dependencies (standalone)
controls: No dependencies (standalone)
core: Depends on physics and controls packages
main: Depends on all packages + external 3D libraries

TypeScript Support

All packages include full TypeScript support:

import type { 
  CharacterConfig,
  SpringSimulatorConfig,
  ControlsState 
} from '@react-3rd-person-character/core';

Testing

Each package includes its own test suite:

# Test physics package
cd packages/physics && npm test
 
# Test controls package
cd packages/controls && npm test
 
# Test core package
cd packages/core && npm test

Contributing

When contributing to the library:

Package-specific changes: Make changes in the appropriate package
Cross-package changes: Update dependencies and exports
Main library: Update re-exports in the main src/index.ts
Tests: Add tests to the specific package
Documentation: Update package-specific documentation

Components Advanced