🕹️ BVHEcctrl

BVHEcctrl is a lightweight, plug-and-play character controller designed for react-three-fiber. It requires no physics engine, and utilizes three-mesh-bvh for highly efficient, triangle-accurate collision detection and response.

🧠 Ideal for web-based 3D experiences such as games, interactive portfolios, and virtual worlds.

📸 Examples

✨ Features

• No physics engine required
• Fast BVH-based collision detection
• Smooth floating capsule movement for stairs, slopes, and uneven surfaces
• Built-in support for:
  • StaticCollider
  • KinematicCollider
  • InstancedStaticCollider

📦 Installation

npm install bvhecctrl

⚙️ How to Use

Step 1: Setup Keyboard Controls and Character Controller

import BVHEcctrl from "bvhecctrl";
import { KeyboardControls } from "@react-three/drei";

const keyboardMap = [
  { name: "forward", keys: ["ArrowUp", "KeyW"] },
  { name: "backward", keys: ["ArrowDown", "KeyS"] },
  { name: "leftward", keys: ["ArrowLeft", "KeyA"] },
  { name: "rightward", keys: ["ArrowRight", "KeyD"] },
  { name: "jump", keys: ["Space"] },
  { name: "run", keys: ["Shift"] },
];

return (
  <KeyboardControls map={keyboardMap}>
    <BVHEcctrl ref={ecctrlRef}>
      <CharacterModel />
    </BVHEcctrl>
  </KeyboardControls>
);

Step 2: Add Colliders to Your Map

import {
  StaticCollider,
  KinematicCollider,
  InstancedStaticCollider,
} from "bvhecctrl";

useFrame((_, delta) => {
  if (kinematicRef.current) kinematicRef.current.rotation.y += delta;
});

return (
  <>
    <StaticCollider>
      <MapModel />
    </StaticCollider>

    <KinematicCollider ref={kinematicRef}>
      <MapModel />
    </KinematicCollider>

    <InstancedStaticCollider>
      <InstancedMapModel />
    </InstancedStaticCollider>
  </>
);

Step 3: Handle Camera Movement

You can use any camera control system that fits your needs — such as <OrbitControls>, <PointerLockControls>, <CameraControls>, or your own custom setup. For smooth and flexible control, I highly recommend using <CameraControls> from @react-three/drei. It even offers built-in camera collision support.

Here’s a simple example using <CameraControls> to follow the character:

useFrame(() => {
  camControlRef.current.moveTo(
    ecctrlRef.current.group.position.x,
    ecctrlRef.current.group.position.y + 0.3,
    ecctrlRef.current.group.position.z,
    true
  );
});

🧱 BVHEcctrl Props

| Prop | Type | Default | Description | | ---------------------------- | ---------------------------------------- | ------------------ | ------------------------------------------------------------- | | debug | boolean | false | Enables visual debugging. | | colliderCapsuleArgs | [number, number, number, number] | [0.3, 0.6, 4, 8] | Capsule shape: [radius, height, capSegments, radialSegments]. | | paused | boolean | false | Freezes character physics and collision response. | | delay | number | 1.5 | Physics delay after initialization (in seconds). | | gravity | number | 9.81 | World gravity. | | fallGravityFactor | number | 4 | Multiplier to increase falling speed. | | maxFallSpeed | number | 50 | Maximum fall velocity cap. | | mass | number | 1 | Virtual mass, affects float behavior. | | sleepTimeout | number | 10 | Time before character enters sleep state when idle. | | slowMotionFactor | number | 1 | Global time scaling (e.g., 0.5 = half-speed). | | turnSpeed | number | 15 | Turn speed when changing direction. | | maxWalkSpeed | number | 3 | Max speed when walking. | | maxRunSpeed | number | 5 | Max speed when running. | | acceleration | number | 30 | Speed increase per second. | | deceleration | number | 20 | Speed decrease when input is released. | | counterAccFactor | number | 0.5 | Extra acceleration multiplier when changing direction. | | airDragFactor | number | 0.3 | Simulated drag while in air. | | jumpVel | number | 5 | Upward velocity when jumping. | | floatCheckType | "RAYCAST" | "SHAPECAST" | "BOTH" | BOTH | Able to switch between different float check type. | | maxSlope | number | 1 | Max walkable surface slope (in radians). | | floatHeight | number | 0.2 | Desired float height above ground. | | floatPullBackHeight | number | 0.25 | Additional distance below ground used to pull character down. | | floatSensorRadius | number | 0.12 | Radius of the sensor used to sense the ground. | | floatSpringK | number | 600 | Spring constant for floating. | | floatDampingC | number | 28 | Damping factor for float spring (prevents oscillation). | | collisionCheckIteration | number | 3 | Number of collision check per frame. | | collisionPushBackVelocity | number | 3 | Extra velocity applied to resolve penetration. | | collisionPushBackDamping | number | 0.1 | Damping applied to the pushback force. | | collisionPushBackThreshold | number | 0.005 | Minimum depth before pushback activates. |

🧱 Collider Component Props

| Prop | Type | Default | Description | | ----------------------- | --------- | ------------- | ------------------------------------------------------------ | | debug | boolean | false | Shows BVH bounds for debugging. | | debugVisualizeDepth | number | 10 | Depth level of BVH to visualize (debug only). | | restitution | number | 0.05 | Bounciness on impact. | | friction | number | 0.8 | Surface friction against character movement. | | excludeFloatHit | boolean | false | If true, this collider is ignored in float sensor checks. | | excludeCollisionCheck | boolean | false | If true, this collider is excluded from collision detection. | | BVHOptions | object | (see below) | Configuration for building the internal BVH tree. |

Default BVHOptions:

{
  strategy: SAH,
  verbose: false,
  setBoundingBox: true,
  maxDepth: 40,
  maxLeafTris: 10,
  indirect: false
}

🎮 Virtual Joystick and Button Integration

BVHEcctrl provides mobile-friendly UI components to control character movement and actions using touch input. Simply import and place <Joystick /> and <VirtualButton /> outside the <Canvas> component:

import { Joystick, VirtualButton } from "bvhecctrl";

<Joystick />

<VirtualButton
  id="run"
  label="RUN"
  buttonWrapperStyle={{ right: "100px", bottom: "40px" }}
/>

<VirtualButton
  id="jump"
  label="JUMP"
  buttonWrapperStyle={{ right: "40px", bottom: "100px" }}
/>

You can define additional components beyond the built-in "run" and "jump" ones, such as:

import { VirtualButton, useButtonStore } from "bvhecctrl";

<VirtualButton id="dance" />;

// Later access it in your logic
const { buttons } = useButtonStore.getState();
console.log(buttons.dance); // true or false

🧱 Joystick Component Props

| Prop | Type | Default | Description | | ---------------------- | --------------------- | ------- | --------------------------------- | | joystickMaxRadius | number | 50 | Maximum drag radius. | | joystickWrapperStyle | React.CSSProperties | - | CSS style for the outer wrapper. | | joystickBaseStyle | React.CSSProperties | - | CSS style for the joystick base. | | joystickKnobStyle | React.CSSProperties | - | CSS style for the draggable knob. |

🧱 VirtualButton Component Props

| Prop | Type | Default | Description | | -------------------- | --------------------- | ------- | --------------------------------------------------------- | | id | string | - | Unique ID to map to actions ("run" & "jump" are handled). | | label | string | - | Optional label text on the button. | | buttonWrapperStyle | React.CSSProperties | - | CSS style for the wrapper container. | | buttonCapStyle | React.CSSProperties | - | CSS style for the button cap. |

🧩 Extra Utilities

Accessing the Controller Ref:

// Access the character group (THREE.Group)
ecctrlRef.current.group;

// Access the character model (THREE.Group)
ecctrlRef.current.model;

// Reset current velocity to zero
ecctrlRef.current.resetLinVel();

// Add linear velocity directly
ecctrlRef.current.addLinVel(THREE.Vector3);

// Set linear velocity directly
ecctrlRef.current.setLinVel(THREE.Vector3);

// Set character movement, can have one or more inputs
ecctrlRef.current.setMovement({
  forward: boolean,
  backward: boolean,
  leftward: boolean,
  rightward: boolean,
  joystick: { x: number; y: number },
  run: boolean,
  jump: boolean,
});

Read-only Character Status:

import { characterStatus } from "bvhecctrl";

characterStatus.position; // THREE.Vector3
characterStatus.linvel; // THREE.Vector3
characterStatus.quaternion; // THREE.Quaternion
characterStatus.inputDir; // THREE.Vector3
characterStatus.movingDir; // THREE.Vector3
characterStatus.isOnGround; // boolean
characterStatus.isOnMovingPlatform; // boolean
characterStatus.animationStatus; // "IDLE" | "WALK" | "RUN" | "JUMP_START" | "JUMP_IDLE" | "JUMP_FALL" | "JUMP_LAND"

Accessing Character Animation Status (global store)

// You can track the current animation state of the character using the global animation store
import { useAnimationStore } from "bvhecctrl";

const animationStatus = useAnimationStore((state) => state.animationStatus); // "IDLE" | "WALK" | "RUN" | "JUMP_START" | "JUMP_IDLE" | "JUMP_FALL" | "JUMP_LAND"

// This value updates reactively and can be used in a useEffect:
useEffect(() => {
  console.log("Animation changed to:", animationStatus);
}, [animationStatus]);

💰 Support This Project

If you find BVHEcctrl helpful, please consider supporting the project.

Your support means a lot and will help me dedicate more time to development, improvements, and documentation.

Every bit of support helps! Whether it’s a donation, a star, or simply sharing the project. Thank you for helping me keep this project moving forward! 🙏

💡 What Add-ons Would You Like to See?

I’m considering offering additional features or paid extensions.
If you're interested, feel free to vote or leave feedback:

• A vanilla three.js version of BVHEcctrl
• Custom gravity support (move on spheres)
• Tutorials on building this controller from scratch
• More experimental features and playground demos

💬 Leave your thoughts on GitHub or join the discussion on the pmndrs Discord.