webxr-first-steps

Welcome to WebXR First Steps! This 2-hour tutorial is designed to help you take your first steps into developing immersive WebXR experiences using Three.js. Whether you’re a web developer looking to expand your skillset or a hobbyist interested in creating virtual reality (VR) applications, this tutorial will guide you through the fundamentals of building interactive 3D worlds for the web.

What You’ll Build

By the end of this tutorial, you’ll have created a fully functional WebXR game where players can use VR controllers to shoot targets, track their score, and enjoy an immersive experience complete with sound, vibration, and smooth animations. Here's what the final experience looks like:

Target Practice Gameplay

Setting Up Your Local Development Environment

To prepare your development environment and get started with building your WebXR experience, follow the steps below:

1. Clone this repository:

   git clone git@github.com:meta-quest/webxr-first-steps.git
   cd webxr-first-steps

2. Verify that you have Node.js and npm installed:

   • Node.js version: 20.x or later
   • npm version: 10.x or later You can check your versions with these commands:

   node -v
   npm -v

3. Install dependencies:

   npm install

4. Run the local development server:

   npm run dev

   After running the above command, your development server will be available at localhost:8081.

Developing with a Headset

You can access the local development server from your XR headset by using one of two methods: via the IP address of your computer or by using ADB with port forwarding.

Accessing the Local Server on Your Headset via IP Address

On most home networks, you can access the local server by entering your computer's IP address and the port number (8081) in the browser on your VR headset. This information is displayed in the Webpack console when you start the server.

For example:

<i> [webpack-dev-server] Project is running at:
<i> [webpack-dev-server] On Your Network (IPv4): https://192.168.0.123:8081/

You might encounter a warning about an invalid certificate when accessing the site from your browser client, which you can safely dismiss to access your site.

Accessing the Local Server on Your Headset via ADB

If accessing via IP address doesn’t work due to network restrictions or firewall settings, you can use ADB (Android Debug Bridge) and port forwarding:

1. Connect your headset to your computer: Use a USB cable and enable developer mode on your headset. Check your device's official documentation for instructions on enabling developer mode.

2. Set up port forwarding: Open Chrome on your computer and navigate to chrome://inspect/#devices. Your headset should appear under Remote Target.

3. Configure port forwarding:

   • Click Port forwarding... in Chrome DevTools.
   • Add a rule to forward port 8081 from your computer to your headset.

You can now access the local server on your headset by entering https://localhost:8081 in the browser. As with the IP address method, you may encounter a certificate warning, which can be dismissed.

Developing with an Emulator

This project includes a built-in emulation setup located in ./src/init.js, powered by IWER (Immersive Web Emulation Runtime) and @iwer/devui. The emulation setup automatically detects native WebXR support in your browser and activates itself if no native WebXR support is found.

If you're already using the Immersive Web Emulator browser extension, the built-in emulation will not conflict with it, and you can safely skip this section. However, if you use other WebXR emulators, we recommend disabling them and using the built-in emulation setup for the best results.

• IWER is a full WebXR runtime, and @iwer/devui provides a developer interface that exposes control over the emulated XR device created by IWER. With this setup, you can manipulate headset and controller transforms, and simulate input events for the emulated controllers.
• Additionally, you can leverage the "Play Mode" button on the top bar of the interface. This feature locks your cursor and allows you to control the emulated XR device like a first-person 3D experience on a PC.

Here’s a showcase of the emulation setup in action:

IWER & IWER/DevUI Showcase

Getting Started

This tutorial is structured into chapters to help you progressively build your WebXR game. Follow each chapter in sequence, as each builds upon concepts introduced in the previous ones.

• Chapter 1: Creating Simple Objects: Learn how to add basic 3D shapes like cubes, spheres, and cones to your scene.
• Chapter 2: Interacting with Controllers: Implement VR controller interactions and trigger actions based on user input.
• Chapter 3: Animating Objects: Make bullets move in the direction of the controller, and learn about time-based animation in WebXR.
• Chapter 4: Loading GLTF Models: Replace simple geometries with more complex, detailed 3D models using the GLTF format.
• Chapter 5: Hit Detection and Score Tracking: Implement proximity-based hit detection, track player progress, and display scores.
• Chapter 6: Finishing Touches: Add audio feedback, haptic feedback, and visual effects to make your game more immersive and polished.

We hope you enjoy working through the tutorial. Happy coding, and have fun building your WebXR game!

Build and Deploy

Once you've completed the development of your WebXR game, you can build and deploy it for others to experience. Here's how you can do that:

Deploying the App with GitHub Pages

This repository includes a ready-to-use GitHub Actions workflow located at .github/workflows/deploy.yml, which automates both the build and deployment to GitHub Pages. Once enabled, every time you push changes to the main branch, a new build will automatically be deployed.

Steps to Enable GitHub Pages Deployment:

1. Fork this repository to your own GitHub account.
2. Navigate to your forked repository’s Settings.
3. Scroll down to the Pages section.
4. Under Build and Deployment, change the Source to GitHub Actions.

Once this is set, GitHub Actions will handle the build and deployment process automatically. Any time you push changes to the main branch, the app will be built and deployed to GitHub Pages without any additional manual steps.

You can monitor the status of the deployment job or manually re-run it via the Actions tab in your GitHub repository.

Deploying to Your Own Hosting Solution

If you prefer to host the app yourself, you’ll need to manually build the app and then deploy the generated files to your hosting provider.

To generate the build, run the following command:

npm run build

This will create a dist folder containing the static files for the app. You can then upload these files to your hosting platform of choice.

Contributing

Please read CONTRIBUTING.md for details on how to contribute to the project.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Agent-ready development

This sample is configured for AI coding agents.

For the best experience in VS Code or Cursor, install the Meta Horizon extension:

https://marketplace.visualstudio.com/items?itemName=meta.meta-vr-dev

This repository also includes agent instructions and MCP configuration for Meta Quest Agentic Tools:

https://github.com/meta-quest/agentic-tools

Suggested first prompt:

Read AGENTS.md, detect what type of Meta Quest sample this is, enable the hzdb MCP server if available, and explain how to build, run, and debug this sample on a Quest device.