r3f-FirstPersonDragControls

A first person controller with free mouse movement for React Three Fiber, using Cannon physics.

FPDC allows you to drag the camera around in first person, freeing the mouse for interactions anywhere on the screen.

Demo

https://r3f-firstpersondragcontrols.vercel.app/

Dependencies

react v18.2.0 or higher

@react-three/fiber v8.3.4 or higher

@react-three/drei v9.77.6 or higher

@react-three/cannon v6.5.2 or higher

Installation

npm install r3f-firstpersondragcontrols or yarn add r3f-firstpersondragcontrols

Usage

import "./App.css";
import { Canvas } from "@react-three/fiber";
import { FirstPersonDragControls, Floor } from "./FirstPersonDragControls";
import { Box, Sky } from "@react-three/drei";
import { Physics } from "@react-three/cannon";

function App() {
  return (
    <div className="App">
      <Canvas
        style={{
          position: "absolute",
          top: 0,
          left: 0,
          width: "100%",
          height: "100%",
        }}
      >
        <Sky />
        <ambientLight intensity={0.5} />
        <Physics gravity={[0, -20, 0]}>
          <Box position={[0, 1, 0]} />
          <FirstPersonDragControls />
          <Floor />
        </Physics>
      </Canvas>
    </div>
  );
}

export default App;

Floor

For the sake of fast prototyping, a <Floor/> object is included in the package. You may use it to place a floor plane that works out of the box with the controller. It is a simple plane with a name prop set to "floor", which is necessary for the player to detect when it is on the floor. You can use any other plane or planes, but you have to set the name prop to "floor" for it to work. It accepts the following props:

| Name | Type | Default | Description | | -------- | ----------- | ------------------------------------------ | --------------------------------------------------------- | | size | number | 100 | Determines the size of the floor plane in a square shape. | | material | JSX Element | <meshStandardMaterial color={"green"} /> | Material applied to plane | | ...props | object | None | Other props that can be passed to the component |

Props

FirstPersonDragControls takes the following props: | Name | Type | Default | Description | | --------------- | ------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------- | | target | Array | [0, 2.5, -3000] | Initial position the camera will be looking at. Set in horizon to not interfere. | | playerMass | Number | 1 | The mass of the player sphere | | initPos | Array | [0, 2.5, 0] | Initial position of the player | | moveSpeed | Number | 2.3 | Player's walking speed | | runSpeed | Number | 3.5 | Player's running speed | | initFov | Number | 45 | Normal field of view | | maxFov | Number | 50 | Maximum field of view when running | | fovLerpFactor | Number | 0.1 | How fast the fov increases and decreases | | jumpVelocity | Number | 5 | Velocity to apply when jumping | | floorName | String | "floor" | Name of the floor plane, necessary to detect when jumping is allowed. <Floor> object included simplifies this. | | keys | Object | Explained below | Key bindings for controls | | controls | React Element | Explained below | Mouse Control Element |

There are two special Object props that can be passed to FirstPersonDragControls.

Keys

Keys prop defines the mapping of the Keyboard key presses and their effect on the player controls. To customize the mapping, change the KeyCode fields to the desired key codes, but keep the Value fields the same. | KeyCode | Type | Value | Description | | ----------- | ------ | ------------ | --------------------- | | KeyW | String | "forward" | Move forward command | | KeyS | String | "backward" | Move backward command | | KeyA | String | "left" | Move left command | | KeyD | String | "right" | Move right command | | Space | String | "space" | Jump command | | ShiftLeft | String | "shift" | Shift command | Here's the default value of the prop:

{ 
  KeyW: "forward", 
  KeyS: "backward", 
  KeyA: "left", 
  KeyD: "right", 
  Space: "space", 
  ShiftLeft: "shift" 
}

By the default configuration, the player controls the movement with classic FPS controls: WASDfor movement, LeftShiftfor running and Space for jumping.

Controls

Controls prop defines the mouse controls for the player. I don't recommend to use anything other than OrbitControls, but if you might, I'd recommend for it to be an element of the Drei library.

The default value is:

 <OrbitControls
  makeDefault
  target={target} // This is the target prop of the FirstPersonDragControls element
  enableZoom={false}
  enablePan={true}
  enableRotate={false}
  panSpeed={2}
  keyPanSpeed={0}
  dampingFactor={0.1}
  mouseButtons={{
    RIGHT: null,
    LEFT: THREE.MOUSE.PAN,
    MIDDLE: null,
  }}
  />

If you want to customise these default OrbitControls values, you have to send the entire object as a prop as shown above, then change or add your desired values. I would recommend to keep the "target" value the same as the target prop in the main element, but customising it also allows you to follow an element if you'd wish to do so. If you want to know more about OrbitControls, please refer to the Drei docs and the three.js docs.

Testing locally

If you want to test the component locally, you can clone the repository and run npm run start or yarn start to start the development server. You can then go to localhost:3000 to see the example scene. To take a peek at the code, check App.js and FirstPersonDragControls.js in the src folder.

Contributing

This is an early version, if you find any bugs or have any suggestions, please open an issue or a pull request. I'd be happy to hear your feedback!

About

This component was created by Dario Sanchez from &why based on the one developed for the #LastSeen game. If you want to see more of our work, check out our project cases and my Twitter .