WebXR First Steps Tutorial

For simple game mechanics where targets are relatively uniform, you can use a proximity-based hit test. This involves iterating through active projectiles (bullets) and checking the distance to visible targets using target.position.distanceTo(bullet.position).

If the distance is below a certain threshold (e.g., 1 unit), a hit is registered. Common actions upon a hit include:

1. Removing the bullet from the scene.
2. Hiding the target temporarily.
3. Respawning the target at a new random position after a delay.
4. Incrementing the score and updating the UI.

Note: For irregularly shaped objects or more precise requirements, use raycasting instead of proximity checks.

function onFrame() {
	// ... unchanged params
	Object.values(bullets).forEach((bullet) => {
		// ... unchanged logic
		targets
			.filter((target) => target.visible)
			.forEach((target) => {
				const distance = target.position.distanceTo(bullet.position);
				if (distance < 1) {
					delete bullets[bullet.uuid];
					scene.remove(bullet);

					// make target disappear, and then reappear at a different place after 2 seconds
					target.visible = false;
					setTimeout(() => {
						target.visible = true;
						target.position.x = Math.random() * 10 - 5;
						target.position.z = -Math.random() * 5 - 5;
					}, 2000);

					score += 10; // Update the score when a target is hit
					updateScoreDisplay(); // Update the rendered troika-three-text object
				}
				});
		});
}

To interact with VR controllers, you can check the controllers object within the onFrame loop. The controllers object provides access to individual controllers (e.g., controllers.right) which contain a gamepad and a raySpace.

Detecting Button Presses

Use the gamepad.getButtonClick(button) method from the gamepad-wrapper library to detect single button presses. This method tracks state frame-by-frame to ensure a single press is registered once.

Spawning Objects at Controller Position

When spawning an object (like a bullet) from a controller, you must align it with the controller's raySpace. Since spawned objects are typically added directly to the scene, you must manually retrieve and apply the controller's world transform:

1. Position: Use raySpace.getWorldPosition(targetPosition).
2. Orientation: Use raySpace.getWorldQuaternion(targetQuaternion).

Note: raySpace represents the XR controller's position and direction in 3D space.

import { XR_BUTTONS } from 'gamepad-wrapper';

function onFrame(
	delta,
	time,
	{ scene, camera, renderer, player, controllers },
) {
	if (controllers.right) {
		const { gamepad, raySpace } = controllers.right;
		if (gamepad.getButtonClick(XR_BUTTONS.TRIGGER)) {
			// 1. Clone a prototype object
			const bullet = bulletPrototype.clone();
			
			// 2. Add to scene
			scene.add(bullet);
			
			// 3. Align with controller's world transform
			raySpace.getWorldPosition(bullet.position);
			raySpace.getWorldQuaternion(bullet.quaternion);
		}
	}
}

The repository provides specific configuration files and installation commands for various AI coding agents and IDEs. Use the following instructions based on your preferred client:

To implement spatialized audio in a WebXR scene, you must attach an AudioListener to the camera and use PositionalAudio objects for sounds that should originate from specific 3D coordinates. Attach the audio objects to the relevant 3D meshes (e.g., a blaster or a scoreboard) so the sound follows them in the scene.

// 1. Create listener and attach to camera
const listener = new THREE.AudioListener();
camera.add(listener);

const audioLoader = new THREE.AudioLoader();

// 2. Create positional audio for a specific object (e.g., laserSound)
const laserSound = new THREE.PositionalAudio(listener);
audioLoader.load('assets/laser.ogg', (buffer) => {
    laserSound.setBuffer(buffer);
    blasterGroup.add(laserSound);
});

// 3. Create positional audio for another object (e.g., scoreSound)
const scoreSound = new THREE.PositionalAudio(listener);
audioLoader.load('assets/score.ogg', (buffer) => {
    scoreSound.setBuffer(buffer);
    scoreText.add(scoreSound);
});

When a user triggers a shot (e.g., via XR_BUTTONS.TRIGGER), clone a bullet prototype, position it at the controller's raySpace, and calculate its trajectory.

To ensure the bullet moves in the direction the controller is pointing, take a forwardVector and apply the controller's world quaternion to it. Store the resulting velocity and the remaining lifespan in the Three.js userData property of the bullet object.

if (controllers.right) {
	const { gamepad, raySpace } = controllers.right;
	if (gamepad.getButtonClick(XR_BUTTONS.TRIGGER)) {
		const bullet = bulletPrototype.clone();
		scene.add(bullet);
		raySpace.getWorldPosition(bullet.position);
		raySpace.getWorldQuaternion(bullet.quaternion);

		const directionVector = forwardVector
			.clone()
			.applyQuaternion(bullet.quaternion);
		bullet.userData = {
			velocity: directionVector.multiplyScalar(bulletSpeed),
			timeToLive: bulletTimeToLive,
		};
		bullets[bullet.uuid] = bullet;
	}
}