About

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.

Mission

Our mission is to provide developers with a simple, powerful, and flexible solution for creating third-person character experiences in React applications. We believe that 3D character interaction should be accessible to all developers, regardless of their experience with complex physics engines or 3D graphics.

Features

Modular Architecture: Separate packages for physics, controls, and core functionality
State Management: XState-driven character state machine for predictable behavior
Physics Integration: Built-in Rapier physics with spring simulators for smooth movement
Mobile Controls: Touch-friendly mobile controls with customizable UI
TypeScript Support: Full TypeScript support with comprehensive type definitions
Fluent API: CharacterBuilder for easy character configuration
Performance Optimized: Designed for 60fps performance on modern devices

Technology Stack

The library integrates and abstracts several powerful technologies:

React Three Fiber (opens in a new tab) - React renderer for Three.js
@react-three/drei (opens in a new tab) - Useful helpers for React Three Fiber
@react-three/rapier (opens in a new tab) - Physics engine integration
Three.js (opens in a new tab) - 3D graphics library
XState (opens in a new tab) - State machine library for predictable state management
Zustand (opens in a new tab) - Lightweight state management

Architecture

The library is structured as a monorepo with separate packages:

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

This modular approach allows developers to:

Use only the packages they need
Reduce bundle size for specific use cases
Contribute to individual components
Maintain clear separation of concerns

Performance

The library is designed with performance in mind:

60fps Target: Optimized for smooth 60fps performance
Efficient Physics: Spring simulators for smooth movement without heavy physics calculations
Lazy Loading: Support for lazy loading of 3D models and components
Memory Management: Proper cleanup and memory management
Mobile Optimization: Optimized for mobile devices with touch controls

Browser Support

Modern Browsers: Chrome, Firefox, Safari, Edge (latest versions)
Mobile Browsers: iOS Safari, Chrome Mobile, Samsung Internet
WebGL Support: Requires WebGL 2.0 support
ES6+: Requires ES6+ JavaScript support

Contributing

We welcome contributions from the community! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.

How to Contribute

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes: Follow the existing code style and patterns
Add tests: Ensure your changes are covered by tests
Submit a pull request: Provide a clear description of your changes

Development Setup

# Clone the repository
git clone https://github.com/ignaciobarocchi/react-3rd-person-character.git
 
# Install dependencies
pnpm install
 
# Run tests
pnpm test
 
# Build packages
pnpm build
 
# Start development server
pnpm dev

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

Physics Package

The physics package includes spring simulation systems originally developed by Matt Black and adapted from the CodeSandbox project (opens in a new tab). We extend our gratitude to Matt for his excellent work on physics simulation.

Community

Thanks to the amazing React Three Fiber community and all contributors who have helped make this library possible.

Support

GitHub Issues: Report bugs or request features (opens in a new tab)
Discussions: Join the community discussions (opens in a new tab)
Documentation: Browse the documentation for detailed guides and examples

Roadmap

Multiplayer Support: Built-in multiplayer character synchronization
Animation System: Advanced animation blending and transitions
VR Support: Virtual reality character controls
More Examples: Additional examples and tutorials
Performance Monitoring: Built-in performance monitoring tools
Accessibility: Improved accessibility features for character controls

Version History

v1.0.0 (Current)

Initial release with core functionality
Physics package with spring simulators
Controls package with mobile and desktop support
Core package with character state management
Comprehensive documentation and examples