### Install BVHEcctrl

Source: https://github.com/pmndrs/bvhecctrl/blob/main/readme.md

Install the package via npm to start using the character controller in your project.

```bash
npm install bvhecctrl
```

--------------------------------

### Setup Keyboard Controls and Character Controller

Source: https://github.com/pmndrs/bvhecctrl/blob/main/readme.md

Configure keyboard mapping and wrap your character model with the BVHEcctrl component.

```javascript
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>
);
```

--------------------------------

### Full Game Setup with BVHEcctrl in React Three Fiber

Source: https://context7.com/pmndrs/bvhecctrl/llms.txt

This snippet sets up a complete 3D game scene using BVHEcctrl. It includes character controller initialization, environment setup with static and kinematic colliders, camera controls that follow the character, and integrates keyboard controls for desktop and virtual buttons for mobile.

```tsx
import { Canvas } from "@react-three/fiber";
import { KeyboardControls, CameraControls, Environment, useGLTF } from "@react-three/drei";
import BVHEcctrl, {
  StaticCollider,
  KinematicCollider,
  Joystick,
  VirtualButton,
  useEcctrlStore,
  useAnimationStore,
  characterStatus,
  type BVHEcctrlApi,
} from "bvhecctrl";
import { useRef, useEffect } from "react";
import { useFrame } from "@react-three/fiber";
import * as THREE from "three";

// Keyboard controls configuration
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"] },
];

function Character() {
  const { scene } = useGLTF("/character.glb");
  return <primitive object={scene} scale={0.5} />;
}

function GameScene() {
  const ecctrlRef = useRef<BVHEcctrlApi>(null);
  const camControlRef = useRef<CameraControls>(null);
  const platformRef = useRef<THREE.Group>(null);

  // Get collider meshes for camera collision
  const colliderMeshesArray = useEcctrlStore((state) => state.colliderMeshesArray);

  // Track animation for effects
  const animationStatus = useAnimationStore((state) => state.animationStatus);

  useEffect(() => {
    if (animationStatus === "JUMP_LAND") {
      // Play landing sound or particle effect
    }
  }, [animationStatus]);

  // Camera follows character + animate platform
  useFrame((state, delta) => {
    // Camera follow
    if (camControlRef.current && ecctrlRef.current?.group) {
      camControlRef.current.moveTo(
        ecctrlRef.current.group.position.x,
        ecctrlRef.current.group.position.y + 0.5,
        ecctrlRef.current.group.position.z,
        true
      );

      // Hide model in first person
      if (ecctrlRef.current.model) {
        ecctrlRef.current.model.visible = camControlRef.current.distance > 1;
      }
    }

    // Animate kinematic platform
    if (platformRef.current) {
      platformRef.current.rotation.y += delta * 0.3;
    }
  });

  return (
    <>
      <CameraControls
        ref={camControlRef}
        colliderMeshes={colliderMeshesArray}
        smoothTime={0.1}
        makeDefault
      />

      <Environment preset="sunset" background />
      <ambientLight intensity={0.5} />
      <directionalLight position={[10, 10, 5]} intensity={1} />

      <KeyboardControls map={keyboardMap}>
        <BVHEcctrl
          ref={ecctrlRef}
          colliderCapsuleArgs={[0.3, 0.6, 4, 8]}
          maxWalkSpeed={3}
          maxRunSpeed={6}
          jumpVel={5}
          gravity={9.81}
        >
          <Character />
        </BVHEcctrl>
      </KeyboardControls>

      {/* Ground */}
      <StaticCollider friction={0.8}>
        <mesh position={[0, -0.5, 0]}>
          <boxGeometry args={[50, 1, 50]} />
          <meshStandardMaterial color="#3a7d44" />
        </mesh>
      </StaticCollider>

      {/* Walls */}
      <StaticCollider>
        <mesh position={[0, 2, -25]}>
          <boxGeometry args={[50, 5, 1]} />
          <meshStandardMaterial color="#666" />
        </mesh>
      </StaticCollider>

      {/* Rotating platform */}
      <KinematicCollider ref={platformRef} active={true}>
        <mesh position={[10, 1, 10]}>
          <cylinderGeometry args={[3, 3, 0.5, 32]} />
          <meshStandardMaterial color="#8844aa" />
        </mesh>
      </KinematicCollider>
    </>
  );
}

// Main App component
export default function App() {
  return (
    <div style={{ width: "100vw", height: "100vh" }}>
      <Canvas shadows>
        <GameScene />
      </Canvas>

      {/* Mobile controls - outside Canvas */}
      <Joystick />
      <VirtualButton
        id="run"
        label="RUN"
        buttonWrapperStyle={{ right: "100px", bottom: "40px" }}
      />
      <VirtualButton
        id="jump"
        label="JUMP"
        buttonWrapperStyle={{ right: "40px", bottom: "100px" }}
      />
    </div>
  );
}

```

--------------------------------

### Access Controller Ref and Utilities

Source: https://github.com/pmndrs/bvhecctrl/blob/main/readme.md

Provides examples for interacting with the character controller reference, including accessing the model group, manipulating velocity, and setting movement inputs.

```javascript
ecctrlRef.current.group;
ecctrlRef.current.model;
ecctrlRef.current.resetLinVel();
ecctrlRef.current.addLinVel(THREE.Vector3);
ecctrlRef.current.setMovement({
  forward: false,
  backward: false,
  leftward: false,
  rightward: false,
  joystick: { x: 0, y: 0 },
  run: false,
  jump: false
});
```

--------------------------------

### Use Joystick Store for Joystick State (React/TypeScript)

Source: https://context7.com/pmndrs/bvhecctrl/llms.txt

This snippet demonstrates using the useJoystickStore to track the virtual joystick's position and active state. It includes a debug overlay to display current values and an AI controller example that programmatically sets joystick input. Dependencies include bvhecctrl.

```tsx
import { useJoystickStore } from "bvhecctrl";
import { useEffect } from "react";

function JoystickDebugOverlay() {
  const { joystickActive, joystickX, joystickY } = useJoystickStore();

  return (
    <div style={{
      position: "fixed",
      top: 10,
      left: 10,
      background: "rgba(0,0,0,0.7)",
      color: "white",
      padding: 10,
    }}>
      <div>Active: {joystickActive ? "Yes" : "No"}</div>
      <div>X: {joystickX.toFixed(2)}</div>
      <div>Y: {joystickY.toFixed(2)}</div>
    </div>
  );
}

// Programmatically control joystick (for AI or automation)
function AIController() {
  const { setJoystick, resetJoystick } = useJoystickStore();

  useEffect(() => {
    // Simulate joystick input
    const interval = setInterval(() => {
      const angle = Date.now() / 1000;
      setJoystick(Math.cos(angle), Math.sin(angle));
    }, 16);

    return () => {
      clearInterval(interval);
      resetJoystick();
    };
  }, []);

  return null;
}
```

--------------------------------

### Use Button Store for Button State Management (React/TypeScript)

Source: https://context7.com/pmndrs/bvhecctrl/llms.txt

This snippet illustrates using the useButtonStore to manage virtual button states, supporting custom button IDs. It shows how to read button states reactively, programmatically control button activity (e.g., simulating a jump), and includes an example of defining custom buttons in the UI. Dependencies include bvhecctrl.

```tsx
import { useButtonStore, VirtualButton } from "bvhecctrl";
import { useEffect } from "react";

function CustomButtonLogic() {
  // Read button states reactively
  const buttons = useButtonStore((state) => state.buttons);

  useEffect(() => {
    if (buttons.dance) {
      console.log("Dance button is pressed!");
    }
    if (buttons.interact) {
      console.log("Interact button is pressed!");
    }
  }, [buttons]);

  return null;
}

// Programmatically control buttons
function AutomatedInput() {
  const { setButtonActive, resetAllButtons } = useButtonStore();

  const simulateJump = () => {
    setButtonActive("jump", true);
    setTimeout(() => setButtonActive("jump", false), 100);
  };

  const simulateRunning = (running: boolean) => {
    setButtonActive("run", running);
  };

  useEffect(() => {
    // Clean up on unmount
    return () => resetAllButtons();
  }, []);

  return (
    <div>
      <button onClick={simulateJump}>Simulate Jump</button>
      <button onMouseDown={() => simulateRunning(true)} onMouseUp={() => simulateRunning(false)}>
        Hold to Run
      </button>
    </div>
  );
}

// Custom buttons in UI
function MobileUI() {
  return (
    <>
      <VirtualButton id="dance" label="DANCE" />
      <VirtualButton id="interact" label="USE" />
      <VirtualButton id="crouch" label="CROUCH" />
    </>
  );
}
```

--------------------------------

### InstancedStaticCollider for Efficient Instanced Mesh Collisions in React Three Fiber

Source: https://context7.com/pmndrs/bvhecctrl/llms.txt

Utilizes the InstancedStaticCollider component for efficient collision detection with instanced meshes, suitable for rendering many identical objects like trees or rocks. The example demonstrates generating random matrices for instance positions and rotations, then applying them to an instanced mesh.

```tsx
import { InstancedStaticCollider } from "bvhecctrl";
import { useRef, useMemo } from "react";
import * as THREE from "three";

function InstancedEnvironment() {
  const meshRef = useRef<THREE.InstancedMesh>(null);
  const count = 100;

  // Generate random positions for instances
  const matrices = useMemo(() => {
    const temp = new THREE.Matrix4();
    const position = new THREE.Vector3();
    const rotation = new THREE.Euler();
    const quaternion = new THREE.Quaternion();
    const scale = new THREE.Vector3(1, 1, 1);

    const matrices: THREE.Matrix4[] = [];

    for (let i = 0; i < count; i++) {
      position.set(
        (Math.random() - 0.5) * 50,
        0,
        (Math.random() - 0.5) * 50
      );
      rotation.set(0, Math.random() * Math.PI * 2, 0);
      quaternion.setFromEuler(rotation);

      temp.compose(position, quaternion, scale);
      matrices.push(temp.clone());
    }

    return matrices;
  }, [count]);

  // Set instance matrices
  useMemo(() => {
    if (meshRef.current) {
      matrices.forEach((matrix, i) => {
        meshRef.current!.setMatrixAt(i, matrix);
      });
      meshRef.current.instanceMatrix.needsUpdate = true;
    }
  }, [matrices]);

  return (
    <InstancedStaticCollider
      debug={false}
      debugVisualizeDepth={10}
      restitution={0.05}
      friction={0.8}
      excludeFloatHit={false}
      excludeCollisionCheck={false}
    >
      <instancedMesh ref={meshRef} args={[undefined, undefined, count]}>
        <boxGeometry args={[1, 2, 1]} />
        <meshStandardMaterial color="brown" />
      </instancedMesh>
    </InstancedStaticCollider>
  );
}

```

--------------------------------

### KinematicCollider for Moving Platforms in React Three Fiber

Source: https://context7.com/pmndrs/bvhecctrl/llms.txt

Implements a KinematicCollider component to handle collisions with moving or rotating geometry such as platforms and elevators. It tracks position and rotation changes to ensure proper character interaction with dynamic surfaces. The example showcases rotating, sliding, and complex motion platforms, as well as an inactive platform.

```tsx
import { KinematicCollider } from "bvhecctrl";
import { useRef } from "react";
import { useFrame } from "@react-three/fiber";
import * as THREE from "three";

function MovingPlatforms() {
  const rotatingPlatformRef = useRef<THREE.Group>(null);
  const slidingPlatformRef = useRef<THREE.Group>(null);
  const complexPlatformRef = useRef<THREE.Group>(null);

  useFrame((state, delta) => {
    const time = state.clock.elapsedTime;

    // Rotating platform
    if (rotatingPlatformRef.current) {
      rotatingPlatformRef.current.rotation.y += delta * 0.5;
    }

    // Sliding platform (side to side)
    if (slidingPlatformRef.current) {
      slidingPlatformRef.current.position.x = Math.sin(time) * 5;
    }

    // Complex motion (rotating + translating)
    if (complexPlatformRef.current) {
      complexPlatformRef.current.rotation.y += delta * 0.3;
      complexPlatformRef.current.position.x = Math.sin(time * 0.5) * 3;
    }
  });

  return (
    <>
      {/* Rotating platform */}
      <KinematicCollider
        ref={rotatingPlatformRef}
        debug={false}
        active={true}               // Set false to pause kinematic updates
        restitution={0.05}
        friction={0.8}
      >
        <mesh position={[0, 0, 15]}>
          <cylinderGeometry args={[5, 5, 0.5, 32]} />
          <meshStandardMaterial color="green" />
        </mesh>
      </KinematicCollider>

      {/* Sliding platform */}
      <KinematicCollider ref={slidingPlatformRef} active={true}>
        <mesh position={[10, 2, 15]}>
          <boxGeometry args={[4, 0.5, 4]} />
          <meshStandardMaterial color="orange" />
        </mesh>
      </KinematicCollider>

      {/* Complex motion platform */}
      <KinematicCollider ref={complexPlatformRef} active={true}>
        <mesh position={[-10, 3, 15]}>
          <boxGeometry args={[3, 0.5, 3]} />
          <meshStandardMaterial color="purple" />
        </mesh>
      </KinematicCollider>

      {/* Inactive platform (acts like static) */}
      <KinematicCollider active={false}>
        <mesh position={[0, 5, 20]}>
          <boxGeometry args={[6, 0.5, 6]} />
          <meshStandardMaterial color="red" />
        </mesh>
      </KinematicCollider>
    </>
  );
}

```

--------------------------------

### Integrate Virtual Joystick and Buttons

Source: https://github.com/pmndrs/bvhecctrl/blob/main/readme.md

Demonstrates how to import and place UI components for mobile input. Shows the usage of built-in controls and how to register custom buttons using the button store.

```javascript
import { Joystick, VirtualButton, useButtonStore } from "bvhecctrl";

<Joystick />

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

<VirtualButton id="dance" />;

// Access custom button state
const { buttons } = useButtonStore.getState();
console.log(buttons.dance);
```

--------------------------------

### Implement Camera Following

Source: https://github.com/pmndrs/bvhecctrl/blob/main/readme.md

Use useFrame to update camera controls to follow the character's position.

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

--------------------------------

### Implement BVHEcctrl Character Controller

Source: https://context7.com/pmndrs/bvhecctrl/llms.txt

Demonstrates how to integrate the BVHEcctrl component with KeyboardControls and CameraControls to create a playable character in an R3F scene.

```tsx
import BVHEcctrl, { characterStatus, type BVHEcctrlApi } from "bvhecctrl";
import { KeyboardControls, CameraControls } from "@react-three/drei";
import { useRef } from "react";
import { useFrame } from "@react-three/fiber";

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"] },
];

function Game() {
  const ecctrlRef = useRef<BVHEcctrlApi>(null);
  const camControlRef = useRef<CameraControls>(null);

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

  return (
    <KeyboardControls map={keyboardMap}>
      <CameraControls ref={camControlRef} />
      <BVHEcctrl
        ref={ecctrlRef}
        debug={false}
        colliderCapsuleArgs={[0.3, 0.6, 4, 8]}
        gravity={9.81}
        fallGravityFactor={4}
        maxFallSpeed={50}
        mass={1}
        turnSpeed={15}
        maxWalkSpeed={3}
        maxRunSpeed={5}
        acceleration={30}
        deceleration={20}
        jumpVel={5}
        floatCheckType="BOTH"
        maxSlope={1}
        floatHeight={0.2}
        floatSpringK={600}
        floatDampingC={28}
        collisionCheckIteration={3}
      >
        <CharacterModel />
      </BVHEcctrl>
    </KeyboardControls>
  );
}
```

--------------------------------

### BVHEcctrl Configuration Props

Source: https://github.com/pmndrs/bvhecctrl/blob/main/readme.md

Overview of the available props for configuring the character controller physics and movement behavior.

```APIDOC
## Component Props: BVHEcctrl

### Description
Configures the physics, movement, and collision behavior of the character controller.

### Parameters
#### Physics & Movement
- **debug** (boolean) - Optional - Enables visual debugging. Default: false
- **paused** (boolean) - Optional - Freezes character physics. Default: false
- **gravity** (number) - Optional - World gravity. Default: 9.81
- **maxWalkSpeed** (number) - Optional - Max speed when walking. Default: 3
- **maxRunSpeed** (number) - Optional - Max speed when running. Default: 5
- **jumpVel** (number) - Optional - Upward velocity when jumping. Default: 5

#### Collision & Floating
- **colliderCapsuleArgs** (array) - Optional - [radius, height, capSegments, radialSegments]. Default: [0.3, 0.6, 4, 8]
- **floatCheckType** (string) - Optional - "RAYCAST" | "SHAPECAST" | "BOTH". Default: "BOTH"
- **floatHeight** (number) - Optional - Desired float height above ground. Default: 0.2
- **floatSpringK** (number) - Optional - Spring constant for floating. Default: 600

### Usage Example
```javascript
<BVHEcctrl 
  debug={true} 
  maxWalkSpeed={4} 
  jumpVel={6} 
  floatCheckType="RAYCAST" 
/>
```
```

--------------------------------

### Use BVHEcctrlApi for Programmatic Control

Source: https://context7.com/pmndrs/bvhecctrl/llms.txt

Shows how to use the controller's ref to manipulate velocity, reset position, and trigger movement programmatically for gameplay mechanics.

```tsx
import BVHEcctrl, { type BVHEcctrlApi } from "bvhecctrl";
import { useRef } from "react";
import * as THREE from "three";

function CharacterController() {
  const ecctrlRef = useRef<BVHEcctrlApi>(null);

  const handleDashForward = () => {
    if (ecctrlRef.current) {
      const dashVelocity = new THREE.Vector3(0, 0, -10);
      ecctrlRef.current.addLinVel(dashVelocity);
    }
  };

  const handleKnockback = () => {
    if (ecctrlRef.current) {
      const knockbackVelocity = new THREE.Vector3(5, 8, 5);
      ecctrlRef.current.setLinVel(knockbackVelocity);
    }
  };

  const handleRespawn = () => {
    if (ecctrlRef.current) {
      ecctrlRef.current.group?.position.set(0, 5, 0);
      ecctrlRef.current.resetLinVel();
    }
  };

  const handleProgrammaticMovement = () => {
    if (ecctrlRef.current) {
      ecctrlRef.current.setMovement({
        forward: true,
        backward: false,
        leftward: false,
        rightward: false,
        joystick: { x: 0, y: 0 },
        run: true,
        jump: false,
      });
    }
  };

  return (
    <BVHEcctrl ref={ecctrlRef}>
      <CharacterModel />
    </BVHEcctrl>
  );
}
```

--------------------------------

### useButtonStore - Button State Store

Source: https://context7.com/pmndrs/bvhecctrl/llms.txt

A Zustand store for managing the state of virtual buttons. It supports built-in buttons like 'run' and 'jump', as well as custom button IDs, allowing for flexible input handling.

```APIDOC
## useButtonStore - Button State Store

A Zustand store that manages the state of all virtual buttons. Supports custom button IDs beyond the built-in "run" and "jump" buttons.

### Description

This store provides a centralized way to manage the active state of various virtual buttons. It allows components to read button states, and other parts of the application to programmatically control button states.

### Usage

#### Reading Button States

```tsx
import { useButtonStore, VirtualButton } from "bvhecctrl";
import { useEffect } from "react";

function CustomButtonLogic() {
  // Read button states reactively
  const buttons = useButtonStore((state) => state.buttons);

  useEffect(() => {
    if (buttons.dance) {
      console.log("Dance button is pressed!");
    }
    if (buttons.interact) {
      console.log("Interact button is pressed!");
    }
  }, [buttons]);

  return null;
}
```

#### Programmatic Button Control

```tsx
import { useButtonStore, VirtualButton } from "bvhecctrl";
import { useEffect } from "react";

function AutomatedInput() {
  const { setButtonActive, resetAllButtons } = useButtonStore();

  const simulateJump = () => {
    setButtonActive("jump", true);
    setTimeout(() => setButtonActive("jump", false), 100);
  };

  const simulateRunning = (running: boolean) => {
    setButtonActive("run", running);
  };

  useEffect(() => {
    // Clean up on unmount
    return () => resetAllButtons();
  }, []);

  return (
    <div>
      <button onClick={simulateJump}>Simulate Jump</button>
      <button onMouseDown={() => simulateRunning(true)} onMouseUp={() => simulateRunning(false)}>
        Hold to Run
      </button>
    </div>
  );
}
```

#### Custom Buttons in UI

```tsx
import { VirtualButton } from "bvhecctrl";

function MobileUI() {
  return (
    <>
      <VirtualButton id="dance" label="DANCE" />
      <VirtualButton id="interact" label="USE" />
      <VirtualButton id="crouch" label="CROUCH" />
    </>
  );
}
```

### State Properties

- **buttons** (Record<string, boolean>): An object where keys are button IDs and values are booleans indicating if the button is active.

### Actions

- **setButtonActive(id: string, active: boolean)**: Sets the active state for a given button ID.
- **resetAllButtons()**: Resets all button states to inactive.
```

--------------------------------

### Manage Collider Meshes with useEcctrlStore

Source: https://context7.com/pmndrs/bvhecctrl/llms.txt

The useEcctrlStore provides access to an array of collider meshes. This is essential for features like camera collision detection or custom raycasting against scene geometry.

```tsx
import { useEcctrlStore } from "bvhecctrl";
import { CameraControls } from "@react-three/drei";

function CameraWithCollision() {
  const colliderMeshesArray = useEcctrlStore((state) => state.colliderMeshesArray);

  return (
    <CameraControls
      colliderMeshes={colliderMeshesArray}
      makeDefault
    />
  );
}
```

--------------------------------

### useJoystickStore - Joystick State Store

Source: https://context7.com/pmndrs/bvhecctrl/llms.txt

A Zustand store that tracks the virtual joystick's position and active state. It provides values for joystickX, joystickY, and joystickActive, enabling custom joystick implementations or external reading of joystick data.

```APIDOC
## useJoystickStore - Joystick State Store

A Zustand store that tracks the virtual joystick's position and active state. Useful for custom joystick implementations or reading joystick values.

### Description

This store provides real-time data about the virtual joystick, including its active status and normalized X/Y coordinates. It can be used to drive character movement or other game mechanics based on player input.

### Usage

#### Reading Joystick Values

```tsx
import { useJoystickStore } from "bvhecctrl";
import { useEffect } from "react";

function JoystickDebugOverlay() {
  const { joystickActive, joystickX, joystickY } = useJoystickStore();

  return (
    <div style={{ position: "fixed", top: 10, left: 10, background: "rgba(0,0,0,0.7)", color: "white", padding: 10 }}>
      <div>Active: {joystickActive ? "Yes" : "No"}</div>
      <div>X: {joystickX.toFixed(2)}</div>
      <div>Y: {joystickY.toFixed(2)}</div>
    </div>
  );
}
```

#### Programmatic Control

```tsx
import { useJoystickStore } from "bvhecctrl";
import { useEffect } from "react";

function AIController() {
  const { setJoystick, resetJoystick } = useJoystickStore();

  useEffect(() => {
    // Simulate joystick input
    const interval = setInterval(() => {
      const angle = Date.now() / 1000;
      setJoystick(Math.cos(angle), Math.sin(angle));
    }, 16);

    return () => {
      clearInterval(interval);
      resetJoystick();
    };
  }, []);

  return null;
}
```

### State Properties

- **joystickActive** (boolean): Indicates if the joystick is currently being touched or is active.
- **joystickX** (number): The normalized X-coordinate of the joystick (-1 to 1).
- **joystickY** (number): The normalized Y-coordinate of the joystick (-1 to 1).

### Actions

- **setJoystick(x: number, y: number)**: Programmatically sets the joystick's X and Y values.
- **resetJoystick()**: Resets the joystick's position and active state to default (0, 0, false).
```

--------------------------------

### useAnimationStore - Animation State Store

Source: https://context7.com/pmndrs/bvhecctrl/llms.txt

A Zustand store for managing and synchronizing character animation states. It allows subscribing to animation status changes and mapping them to specific animation clips for playback.

```APIDOC
## useAnimationStore - Animation State Store

A Zustand store that provides reactive access to the character's current animation status. Useful for synchronizing character animations with the controller state.

### Description

This store exposes the current animation status of the character, allowing other components to react to changes and update animations accordingly. It maps predefined animation statuses (like IDLE, WALK, RUN) to specific animation clip names.

### Usage

```tsx
import { useAnimationStore, type CharacterAnimationStatus } from "bvhecctrl";
import { useEffect, useRef } from "react";
import { useAnimations, useGLTF } from "@react-three/drei";

function AnimatedCharacter() {
  const { scene, animations } = useGLTF("/character.glb");
  const { actions } = useAnimations(animations, scene);

  // Subscribe to animation status changes
  const animationStatus = useAnimationStore((state) => state.animationStatus);

  useEffect(() => {
    // Map controller status to animation clips
    const animationMap: Record<CharacterAnimationStatus, string> = {
      "IDLE": "Idle",
      "WALK": "Walk",
      "RUN": "Run",
      "JUMP_START": "JumpStart",
      "JUMP_IDLE": "JumpIdle",
      "JUMP_FALL": "JumpFall",
      "JUMP_LAND": "JumpLand",
    };

    const clipName = animationMap[animationStatus];
    const action = actions[clipName];

    if (action) {
      // Crossfade to new animation
      action.reset().fadeIn(0.2).play();

      return () => {
        action.fadeOut(0.2);
      };
    }
  }, [animationStatus, actions]);

  return <primitive object={scene} />;
}
```

### State Properties

- **animationStatus** (CharacterAnimationStatus): The current animation status of the character.
```

--------------------------------

### Configure Default BVH Options

Source: https://github.com/pmndrs/bvhecctrl/blob/main/readme.md

Defines the default configuration object for building the internal Bounding Volume Hierarchy (BVH) tree, including settings for strategy, depth, and leaf triangle limits.

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

--------------------------------

### Create Virtual Buttons for Game Actions

Source: https://context7.com/pmndrs/bvhecctrl/llms.txt

VirtualButton components enable touch-based interaction for game actions. State can be monitored using the useButtonStore hook to trigger logic based on button presses.

```tsx
import { VirtualButton, useButtonStore } from "bvhecctrl";

function MobileButtons() {
  return (
    <VirtualButton
      id="attack"
      label="ATK"
      buttonWrapperStyle={{ position: "fixed", right: "40px", bottom: "180px" }}
    />
  );
}

function GameLogic() {
  const unsubscribe = useButtonStore.subscribe(({ buttons }) => {
    if (buttons.attack) console.log("Attack button pressed!");
  });
  return null;
}
```

--------------------------------

### Accessing Character Animation Status via Global Store

Source: https://github.com/pmndrs/bvhecctrl/blob/main/readme.md

Demonstrates how to import and use the useAnimationStore hook to retrieve the current animation state of a character. The state is reactive, allowing for integration with React hooks like useEffect to respond to animation transitions.

```javascript
import { useAnimationStore } from "bvhecctrl";

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

useEffect(() => {
  console.log("Animation changed to:", animationStatus);
}, [animationStatus]);
```

--------------------------------

### Use Animation Store for Character Animations (React/TypeScript)

Source: https://context7.com/pmndrs/bvhecctrl/llms.txt

This snippet shows how to use the useAnimationStore to synchronize character animations with controller state. It subscribes to animation status changes and maps them to specific animation clips, crossfading between animations using React Three Drei. Dependencies include bvhecctrl and @react-three/drei.

```tsx
import { useAnimationStore, type CharacterAnimationStatus } from "bvhecctrl";
import { useEffect, useRef } from "react";
import { useAnimations, useGLTF } from "@react-three/drei";

function AnimatedCharacter() {
  const { scene, animations } = useGLTF("/character.glb");
  const { actions } = useAnimations(animations, scene);

  // Subscribe to animation status changes
  const animationStatus = useAnimationStore((state) => state.animationStatus);

  useEffect(() => {
    // Map controller status to animation clips
    const animationMap: Record<CharacterAnimationStatus, string> = {
      "IDLE": "Idle",
      "WALK": "Walk",
      "RUN": "Run",
      "JUMP_START": "JumpStart",
      "JUMP_IDLE": "JumpIdle",
      "JUMP_FALL": "JumpFall",
      "JUMP_LAND": "JumpLand",
    };

    const clipName = animationMap[animationStatus];
    const action = actions[clipName];

    if (action) {
      // Crossfade to new animation
      action.reset().fadeIn(0.2).play();

      return () => {
        action.fadeOut(0.2);
      };
    }
  }, [animationStatus, actions]);

  return <primitive object={scene} />;
}
```

--------------------------------

### Add Colliders to Scene

Source: https://github.com/pmndrs/bvhecctrl/blob/main/readme.md

Implement Static, Kinematic, and InstancedStatic colliders to define the environment collision boundaries.

```javascript
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>
  </>
);
```

--------------------------------

### Implement Virtual Joystick for Mobile Controls

Source: https://context7.com/pmndrs/bvhecctrl/llms.txt

The Joystick component provides touch-based movement input. It must be placed outside the React Three Fiber Canvas element to render as HTML overlays.

```tsx
import { Joystick } from "bvhecctrl";

function MobileControls() {
  return (
    <>
      <Joystick />
      <Joystick
        joystickMaxRadius={60}
        joystickWrapperStyle={{ position: "fixed", left: "20px", bottom: "20px" }}
      />
    </>
  );
}
```

--------------------------------

### InstancedStaticCollider Component

Source: https://context7.com/pmndrs/bvhecctrl/llms.txt

The InstancedStaticCollider component provides optimized collision detection for large numbers of identical objects using InstancedMesh.

```APIDOC
## COMPONENT InstancedStaticCollider

### Description
A collider optimized for instanced meshes, enabling efficient collision detection with many identical objects like trees or rocks.

### Props
- **debug** (boolean) - Optional - Enables visual debugging.
- **debugVisualizeDepth** (number) - Optional - Sets the depth for the debug visualization.
- **restitution** (number) - Optional - Bounciness of the collider.
- **friction** (number) - Optional - Surface friction coefficient.
- **excludeFloatHit** (boolean) - Optional - Whether to ignore floating object hits.
- **excludeCollisionCheck** (boolean) - Optional - Whether to disable collision checks for this instance group.

### Usage Example
<InstancedStaticCollider debug={false} restitution={0.05}>
  <instancedMesh ref={meshRef} args={[undefined, undefined, count]}>
    <boxGeometry />
    <meshStandardMaterial />
  </instancedMesh>
</InstancedStaticCollider>
```

--------------------------------

### Accessing Global Character State with characterStatus

Source: https://context7.com/pmndrs/bvhecctrl/llms.txt

The `characterStatus` object provides read-only access to the character's current state, including position, velocity, and animation status. It's useful for UI, sound effects, or game logic. The `useAnimationStore` hook can be used for reactive updates to animation status.

```tsx
import { characterStatus, useAnimationStore } from "bvhecctrl";
import { useFrame } from "@react-three/fiber";
import { useEffect } from "react";

function CharacterStateMonitor() {
  // Read character status every frame
  useFrame(() => {
    // Position and velocity (THREE.Vector3)
    const position = characterStatus.position;
    const velocity = characterStatus.linvel;

    // Rotation (THREE.Quaternion)
    const rotation = characterStatus.quaternion;

    // Movement directions (THREE.Vector3)
    const inputDirection = characterStatus.inputDir;
    const movingDirection = characterStatus.movingDir;

    // Ground state (boolean)
    const isOnGround = characterStatus.isOnGround;
    const isOnMovingPlatform = characterStatus.isOnMovingPlatform;

    // Animation status
    // "IDLE" | "WALK" | "RUN" | "JUMP_START" | "JUMP_IDLE" | "JUMP_FALL" | "JUMP_LAND"
    const animationStatus = characterStatus.animationStatus;

    // Example: Update UI or trigger effects
    if (velocity.length() > 10) {
      console.log("Character moving fast!");
    }
  });

  // Reactive animation status via Zustand store
  const animationStatus = useAnimationStore((state) => state.animationStatus);

  useEffect(() => {
    console.log("Animation changed to:", animationStatus);
    // Trigger sound effects, particles, etc.
  }, [animationStatus]);

  return null;
}
```

--------------------------------

### Read Character Status

Source: https://github.com/pmndrs/bvhecctrl/blob/main/readme.md

Shows how to import and access the read-only character status object to retrieve real-time data like position, velocity, and current animation state.

```javascript
import { characterStatus } from "bvhecctrl";

console.log(characterStatus.position);
console.log(characterStatus.isOnGround);
console.log(characterStatus.animationStatus);
```

--------------------------------

### Implementing Static Colliders with StaticCollider

Source: https://context7.com/pmndrs/bvhecctrl/llms.txt

The `StaticCollider` component is used for non-moving environment geometry. It merges child meshes, generates BVH trees for efficient collision detection, and can be configured with various physics properties like restitution and friction. It also supports BVH generation options and debugging visualizations.

```tsx
import { StaticCollider } from "bvhecctrl";
import { useGLTF } from "@react-three/drei";

function StaticEnvironment() {
  const mapModel = useGLTF("/environment.glb");

  return (
    <>
      {/* Basic static collider */}
      <StaticCollider>
        <primitive object={mapModel.scene.clone()} />
      </StaticCollider>

      {/* Static collider with custom physics properties */}
      <StaticCollider
        debug={true}                    // Show BVH debug visualization
        debugVisualizeDepth={10}        // BVH visualization depth
        bvhName="MainFloor"             // Identifier for debugging
        restitution={0.05}              // Bounciness (0-1)
        friction={0.8}                  // Surface friction (0-1)
        excludeFloatHit={false}         // If true, ignored by float sensor
        excludeCollisionCheck={false}   // If true, excluded from collision
        BVHOptions={{
          strategy: "SAH",              // Split strategy
          verbose: false,
          setBoundingBox: true,
          maxDepth: 40,
          maxLeafTris: 10,
          indirect: false,
        }}
      >
        <mesh position={[0, -1, 0]}>
          <boxGeometry args={[100, 1, 100]} />
          <meshStandardMaterial color="gray" />
        </mesh>
      </StaticCollider>

      {/* Slide/ramp - excluded from float detection */}
      <StaticCollider excludeFloatHit={true}>
        <mesh position={[0, 2, 10]} rotation={[0.3, 0, 0]}>
          <boxGeometry args={[5, 0.2, 10]} />
          <meshStandardMaterial color="blue" />
        </mesh>
      </StaticCollider>
    </>
  );
}
```

--------------------------------

### KinematicCollider Component

Source: https://context7.com/pmndrs/bvhecctrl/llms.txt

The KinematicCollider component is used for moving or rotating geometry, such as platforms or elevators, ensuring correct character interaction.

```APIDOC
## COMPONENT KinematicCollider

### Description
A collider component designed for moving or rotating geometry. It tracks position and rotation changes to handle character interaction with moving surfaces.

### Props
- **ref** (React.RefObject) - Required - Reference to the underlying Three.js Group or Mesh.
- **active** (boolean) - Optional - If false, kinematic updates are paused, acting like a static collider.
- **restitution** (number) - Optional - Bounciness of the collider.
- **friction** (number) - Optional - Surface friction coefficient.
- **debug** (boolean) - Optional - Enables visual debugging of the collider bounds.

### Usage Example
<KinematicCollider ref={ref} active={true} restitution={0.05} friction={0.8}>
  <mesh>...</mesh>
</KinematicCollider>
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.