ecctrl

Ecctrl uses subpath exports to allow you to import only the specific systems you need, reducing bundle size. You can also use ecctrl/all to import every public subpath, which is useful for prototyping.

Common import patterns:

• Core character controller: ecctrl
• Vehicles: ecctrl/vehicle
• Input components: ecctrl/input
• Animation: ecctrl/animation
• Gravity: ecctrl/gravity
• Camera: ecctrl/camera
• Time: ecctrl/time
• Curves: ecctrl/curves
• Leva integration: ecctrl/leva

import { Ecctrl } from "ecctrl";
import { EcctrlVehicle, ShapeCastWheel, ThrustPropeller } from "ecctrl/vehicle";
import { Joystick, VirtualButton } from "ecctrl/input";
import { EcctrlAnimationStateController } from "ecctrl/animation";
import { useCustomGravity } from "ecctrl/gravity";
import { EcctrlCameraControls } from "ecctrl/camera";
import { TimeControl } from "ecctrl/time";
import { bakeCurveLUT, evaluateCurveLUT } from "ecctrl/curves";
import { CurveEditorPlugin } from "ecctrl/leva";

To use custom gravity fields instead of Rapier's global gravity, you must:

1. Set the <Physics> gravity to [0, 0, 0] to prevent forces from stacking.
2. Add the enableCustomGravity prop to the <Ecctrl> component.
3. Use the useCustomGravity hook to define a gravity field function that calculates gravity based on a body's position.

import { useEffect } from "react";
import * as THREE from "three";
import { Physics } from "@react-three/rapier";
import { Ecctrl } from "ecctrl";
import { useCustomGravity } from "ecctrl/gravity";

const center = new THREE.Vector3(0, 20, 0);
const gravity = new THREE.Vector3();

function GravitySetup() {
  const setGravityField = useCustomGravity((state) => state.setGravityField);

  useEffect(() => {
    setGravityField((bodyPos) => gravity.subVectors(center, bodyPos).normalize().multiplyScalar(9.81));
  }, [setGravityField]);

  return null;
}

export function Scene() {
  return (
    <Physics gravity={[0, 0, 0]}>
      <GravitySetup />
      <Ecctrl enableCustomGravity>
        <CharacterModel />
      </Ecctrl>
    </Physics>
  );
}

Use the useCustomGravity hook to define non-standard gravity environments (e.g., radial gravity or directional fields).

Workflow:

1. Call useCustomGravity to get the setGravityField setter.
2. Define a function (pos: THREE.Vector3) => THREE.Vector3 that returns the gravity vector for a given world position.
3. Use setGravityField to update the field. For per-frame changes, keep the function reference stable and update internal refs used by the function to avoid unnecessary re-renders.

import { useCustomGravity, type CustomGravityState } from "ecctrl/gravity";

const setGravityField = useCustomGravity((state) => state.setGravityField);
const center = useRef(new THREE.Vector3(0, 20, 0));
const gravity = useMemo(() => new THREE.Vector3(), []);

useEffect(() => {
  setGravityField((pos) => {
    // Example: Radial gravity pulling towards 'center'
    return gravity.subVectors(center.current, pos).normalize().multiplyScalar(9.81);
  });
}, [setGravityField, gravity]);

Ecctrl uses a lightweight animation state resolver. The controller writes the current state into useEcctrlAnimationStore, which you can consume to drive your model's animations.

Default States: "IDLE" | "WALK" | "RUN" | "JUMP_START" | "JUMP_IDLE" | "JUMP_FALL" | "JUMP_LAND"

Basic Setup:

1. Use EcctrlAnimationStateController to link the Ecctrl handle to the animation store.
2. Consume useEcctrlAnimationStore in your model component to react to state changes.

Custom State Mapping: Pass a resolver to EcctrlAnimationStateController to implement custom logic (e.g., switching to RUN based on moveSpeed). Use resolveEcctrlAnimationState(ctx) within your resolver to fall back to default behavior.

import { useEffect, useRef } from "react";
import { Ecctrl, type EcctrlHandle } from "ecctrl";
import { EcctrlAnimationStateController, useEcctrlAnimationStore } from "ecctrl/animation";
import { useAnimations, useGLTF } from "@react-three/drei";

const ANIMATION_MAP = {
  IDLE: "Idle",
  WALK: "Walk",
  RUN: "Run",
  JUMP_START: "Jump_Start",
  JUMP_IDLE: "Jump_Idle",
  JUMP_FALL: "Jump_Fall",
  JUMP_LAND: "Jump_Land",
} as const;

function AnimatedCharacterModel() {
  const group = useRef(null);
  const { scene, animations } = useGLTF("/character.glb");
  const { actions } = useAnimations(animations, group);
  const animationState = useEcctrlAnimationStore((state) => state.animationState);

  useEffect(() => {
    const action = actions[ANIMATION_MAP[animationState]];
    if (!action) return;

    action.reset().fadeIn(0.15).play();
    return () => action.fadeOut(0.15);
  }, [actions, animationState]);

  return (
    <group ref={group}>
      <primitive object={scene} />
    </group>
  );
}

function CharacterWithAnimation() {
  const ecctrl = useRef<EcctrlHandle>(null);

  return (
    <>
      <EcctrlAnimationStateController ecctrl={ecctrl} />
      <Ecctrl ref={ecctrl}>
        <AnimatedCharacterModel />
      </Ecctrl>
    </>
  );
}

Drones are built using EcctrlVehicle combined with ThrustPropeller modules. The vehicle acts as the 'flight brain', mixing throttle and managing stability.

Drone Control Modes:

• POSITION: Position-targeted flight. The controller stabilizes tilt, yaw, and vertical movement based on a target position.
• VELOCITY: Manual velocity-style flight. Input maps to target horizontal, vertical, yaw, pitch, and roll behavior.

Propeller Configuration:

• maxThrust: Maximum thrust per propeller.
• torqueRatio: Reaction torque ratio.
• invertThrust: Inverts the thrust direction.
• invertTorque: Inverts the reaction torque direction.

import { EcctrlVehicle, ThrustPropeller } from "ecctrl/vehicle";
import { CuboidCollider } from "@react-three/rapier";

<EcctrlVehicle
  droneConfig={{
    controlMode: "POSITION",
    maxHorizSpeed: 20,
    maxVertSpeed: 8,
    maxTiltAngle: Math.PI / 4,
  }}
>
  <CuboidCollider args={[0.6, 0.15, 0.6]} />
  <ThrustPropeller position={[1, 0, 1]} />
  <ThrustPropeller position={[-1, 0, 1]} invertTorque />
  <ThrustPropeller position={[1, 0, -1]} invertTorque />
  <ThrustPropeller position={[-1, 0, -1]} />
</EcctrlVehicle>