GamepadPose.linearVelocity — Eigenschaft · JavaScript-Referenz

Signatur

GamepadPose.linearVelocity

Beschreibung

GamepadPose.linearVelocity gibt an, wie schnell und in welche Richtung sich ein getrackter Controller, etwa ein VR-Motion-Controller, gerade im Raum bewegt. Der Wert ist ein Float32Array mit drei Elementen [x, y, z]. Jedes Element steht für die Geschwindigkeit entlang der jeweiligen Achse in Metern pro Sekunde. Wie bei WebVR üblich zeigt die x-Achse nach rechts, die y-Achse nach oben und die negative z-Achse nach vorn.

An das GamepadPose-Objekt kommt man über die Eigenschaft pose eines Gamepad-Objekts, zum Beispiel navigator.getGamepads()[0].pose. Die Geschwindigkeit ist nützlich für physikbasierte Interaktionen. Ein typischer Fall ist das Werfen eines virtuellen Objekts: Beim Loslassen übernimmt das Objekt die aktuelle Geschwindigkeit der Hand. Außerdem lässt sich damit die Position vorausberechnen, um Latenz auszugleichen.

Kann das Gerät keine lineare Geschwindigkeit melden, ist der Wert null. Ob das der Fall ist, zeigt die Eigenschaft GamepadPose.hasPosition. Der Wert ist eine Momentaufnahme. Deshalb sollte man ihn in jedem Frame neu auslesen, am besten innerhalb von requestAnimationFrame.

Rückgabewert

Typ

Float32Array | null

Beschreibung

Ein Float32Array mit drei Werten [x, y, z] in m/s oder null, wenn das Gerät keine Geschwindigkeitsdaten liefert.

Beispiele

Geschwindigkeit eines Controllers auslesen (mit Prüfung, ob die API vorhanden ist)

const logVelocity = () => {
  const pads = navigator.getGamepads?.() ?? [];
  for (const pad of pads) {
    // pose gibt es nur, wenn die Gamepad-Erweiterung unterstützt wird
    const velocity = pad?.pose?.linearVelocity;
    if (!velocity) continue;
    const [x, y, z] = velocity;
    console.log(`${pad.id}: x=${x.toFixed(2)} y=${y.toFixed(2)} z=${z.toFixed(2)} m/s`);
  }
};

window.addEventListener('gamepadconnected', () => logVelocity());

OpenVR Controller: x=0.12 y=-0.03 z=-1.45 m/s

Geschwindigkeit als Betrag in jedem Frame berechnen

const speedOf = (v) => Math.hypot(v[0], v[1], v[2]);

const loop = () => {
  const pad = navigator.getGamepads?.()[0];
  const v = pad?.pose?.linearVelocity;
  if (v) {
    const speed = speedOf(v);
    if (speed > 3) console.log(`Schnelle Bewegung: ${speed.toFixed(1)} m/s`);
  }
  requestAnimationFrame(loop);
};

requestAnimationFrame(loop);

Schnelle Bewegung: 3.4 m/s

Wurfgeschwindigkeit beim Loslassen übernehmen

const ball = { position: [0, 1, 0], velocity: [0, 0, 0] };
let wasPressed = false;

const update = () => {
  const pad = navigator.getGamepads?.()[0];
  if (pad?.pose) {
    const pressed = pad.buttons[0]?.pressed ?? false;
    // Trigger losgelassen: Ball bekommt die Handgeschwindigkeit
    if (wasPressed && !pressed && pad.pose.linearVelocity) {
      ball.velocity = Array.from(pad.pose.linearVelocity);
      console.log('Wurf mit', ball.velocity);
    }
    wasPressed = pressed;
  }
  requestAnimationFrame(update);
};

requestAnimationFrame(update);

Wurf mit [0.8, 1.2, -2.5]

// Wichtig · Fallstricke

Veraltet und experimentell: GamepadPose gehört zur WebVR-Gamepad-Erweiterung. Diese war nur in einzelnen Browsern verfügbar, etwa in Firefox mit dom.gamepad.extensions.enabled oder in Chrome mit WebVR-Flags, und wurde inzwischen weitgehend entfernt. Für neue Projekte ist die WebXR Device API gedacht, dort mit XRPose.linearVelocity.
Immer auf null prüfen: Sowohl gamepad.pose als auch linearVelocity können null oder undefined sein. Optionales Verketten (?.) schützt vor Laufzeitfehlern.
Momentaufnahme: In Chrome sind Gamepad-Objekte Momentaufnahmen. Man sollte navigator.getGamepads() deshalb in jedem Frame neu aufrufen, statt eine alte Referenz aufzubewahren.
Das zurückgegebene Float32Array kann bei der nächsten Aktualisierung wiederverwendet werden. Wer die Werte speichern will, sollte sie kopieren, zum Beispiel mit Array.from().
Die Gamepad-API steht nur in einem sicheren Kontext (HTTPS) zur Verfügung und kann durch eine Permissions-Policy (gamepad) gesperrt sein.

Siehe auch

GamepadPose GamepadPose.angularVelocity GamepadPose.linearAcceleration GamepadPose.position GamepadPose.hasPosition Gamepad.pose Navigator.getGamepads()