gamepad-first-person-controls.md

GamepadFirstPersonControls

A ready-to-use GamepadControls subclass that maps gamepad inputs to Three.js FirstPersonControls - first-person movement and camera look - all driven by analog sticks and triggers.

Built on top of GamepadControls, it inherits the full Web Gamepad API lifecycle (connect/disconnect events, per-frame polling, and dispose()), so you only need to instantiate it and drop update() into your render loop. Gamepad input is additive with keyboard/mouse input - both sources work simultaneously.

All bindings and speeds are configurable via the options parameter.

Default Bindings

Input	Action
Left stick	Move forward / backward / strafe
Left trigger (analog)	Move up
Right trigger (analog)	Move down
Right stick	Look (yaw and pitch)

Every binding is remappable via the options parameter.

Constructor

new GamepadFirstPersonControls(controls, options?)

Parameter	Type	Description
controls	FirstPersonControls	Required. The Three.js FirstPersonControls instance to wrap.
options	Partial<GamepadFirstPersonControlsOptions>	Optional configuration. Any property not provided falls back to its default.

options

Property	Type	Default	Description
moveSpeed	number	1.0	Multiplier on FirstPersonControls.movementSpeed for translation.
lookSpeed	number	1.0	Multiplier on FirstPersonControls.lookSpeed for camera look.
deadzone	number	0.1	Axis dead zone threshold in the range [0, 1].
axisMoveForward	number	1	Axis index for forward / backward movement (left stick Y).
axisMoveRight	number	0	Axis index for left / right strafe movement (left stick X).
axisLookX	number	2	Axis index for horizontal look - yaw (right stick X).
axisLookY	number	3	Axis index for vertical look - pitch (right stick Y).
buttonMoveUp	number	6	Button index for move up - analog trigger value (left trigger).
buttonMoveDown	number	7	Button index for move down - analog trigger value (right trigger).

moveSpeed and lookSpeed multiply FirstPersonControls' own movementSpeed and lookSpeed, so adjusting those properties affects both input sources at once. Gamepad look respects lookVertical, and forward movement respects heightSpeed, heightCoef, heightMin, and heightMax.

Properties

Inherits all properties from GamepadControls.

Events

Inherits all events from GamepadControls.

Types

Type	Description
GamepadFirstPersonControlsOptions	Type of the options parameter accepted by the GamepadFirstPersonControls constructor.

Usage

import { Timer } from "three";
import { FirstPersonControls } from "three/addons/controls/FirstPersonControls.js";
import { GamepadFirstPersonControls } from "three-gamepad-controls";

const firstPersonControls = new FirstPersonControls(
  camera,
  renderer.domElement,
);
firstPersonControls.movementSpeed = 5;
firstPersonControls.lookSpeed = 0.005;
const gamepadFirstPersonControls = new GamepadFirstPersonControls(
  firstPersonControls,
);

gamepadFirstPersonControls.addEventListener("connected", (event) => {
  console.log("Gamepad connected:", event.gamepad.id);
});

const timer = new Timer();

renderer.setAnimationLoop((timestamp) => {
  timer.update(timestamp);
  const delta = timer.getDelta();
  gamepadFirstPersonControls.update(delta); // 1. read gamepad -> apply movement & sync look
  firstPersonControls.update(delta);        // 2. apply keyboard / mouse input
  renderer.render(scene, camera);
});

// When done:
gamepadFirstPersonControls.dispose();