CharacterControl

Ecctrl Floating Capsule Character Controller

Pmndrs/ecctrl is a simple web based character controller build on react-three-fiber and react-three-rapier. It provides a playground demo where you can experience the following features:

1. Seamless movement over small obstacles
2. Enhanced control with floating force incorporating spring and damping forces
3. Rigidbody character functionality for interaction with the game environment
4. Customizable ground friction for tailored control
5. Realistic simulation with applied mass on supporting surfaces
6. Smooth integration with moving and rotating platforms

New Features

(2024-6-24) FixedCamera Mode:

• The “FixedCamera” mode automatically rotates the camera as the character turns (similar to the controls in Coastal World). You can activate it with the following code:

``

Check out the featurelog.md for details on previous updates and features.

Project Link

Live Demo: Floating Capsule Character Controller

Local Setup

Download Node.js. Run this followed commands:

# Install dependencies (only the first time)
npm install

# Run the local server at localhost:5173
npm run dev

# Build for production in the example/exampleDist/ directory
vite build -c vercelVite.config.js

How To Use

Basic Controls (CodeSandbox Demo)

npm install ecctrl

import Ecctrl, { EcctrlAnimation } from "ecctrl";

To get started, set up your keyboard map using KeyboardControls. Then, wrap your character model within ``:

…

Here are all the default properties you can play with for ``:

…

Apply Character Animations (CodeSandbox Demo)

If you want to apply character animations, prepare the character url and customize the animationSet with your own animation names. Change the Ecctrl property animated to true and wrap your character model inside `` tag:

…

(Advanced) Add and Personalize Additional Animations

For advanced animation setups, download all files and follow these steps:

1. In CharacterModel.jsx, expand the animationSet with additional animations:

// Rename your character animations here
const animationSet = {
  idle: "Idle",
  walk: "Walk",
  run: "Run",
  jump: "Jump_Start",
  jumpIdle: "Jump_Idle",
  jumpLand: "Jump_Land",
  fall: "Climbing",
  action1: "Wave",
  action2: "Dance",
  action3: "Cheer",
  action4: "Attack(1h)", // This is special action which can be trigger while walking or running
  //additinalAnimation: "additinalAnimationName",
};

1. In useGame.jsx, create a trigger function for the new animation:

…

1. In CharacterController.jsx, initialize the trigger function and call it when needed:

…

EcctrlJoystick and Touch buttons

To get start, simply import EcctrlJoystick from ecctrl

import { EcctrlJoystick } from "ecctrl";

Place `` outside of your canvas component, and you're done!

//...
  
  
    {/* ... */}
  
//...

You can also add lights or additional meshs like so (note: this will create components twice, once inside the joystick's scene, another inside the buttons' scene, so keep an eye on performance):

//...
  
    
    
      
    
  
  
    {/* ... */}
  
//...

Additionally, you can change components' material, geometry, or texture as you like:

//...
  
  
    {/* ... */}
  
//...

Here are all the properties you can play with for ``:

EcctrlJoystickProps: {
    // Joystick props
    children?: ReactNode;
    joystickRunSensitivity?: number; // Sensitivity for transitioning to the running state. The default value is 0.9 (valid range: 0  state.setJoystick);
const resetJoystick = useJoystickControls((state) => state.resetJoystick);
const pressButton1 = useJoystickControls((state) => state.pressButton1);
const releaseAllButtons = useJoystickControls(
  (state) => state.releaseAllButtons
);
//...
// call the proper fuctions
setJoystick(joystickDis, joystickAng, runState);
// or
pressButton1();

Ecctrl Mode

Activate different modes in Ecctrl by including the desired mode inside Ecctrl component: ``.

1. "PointToMove" Mode (CodeSandbox Demo)

This mode doesn't require keyboard controls and is designed for click-to-move or path-following features.

import { useGame } from "ecctrl";
// ...
const setMoveToPoint = useGame((state) => state.setMoveToPoint);
// ...
// call function setMoveToPoint(), whenever character needs to move
setMoveToPoint(point); // "point" is a vec3 value

(Optional) First-person view setup

If you would like to quickly set up a first-person mode, you can modify these props to achieve that:

Contributions

I appreciate your interest in this project! If you have any feedback, suggestions, or resources related to the controller, please feel free to share.

Thank you!