{"id":15023772,"url":"https://github.com/meta-quest/webxr-first-steps","last_synced_at":"2025-09-13T05:40:17.177Z","repository":{"id":175169865,"uuid":"617306476","full_name":"meta-quest/webxr-first-steps","owner":"meta-quest","description":"Your first steps into immersive web development with WebXR.","archived":false,"fork":false,"pushed_at":"2024-10-15T20:29:17.000Z","size":60085,"stargazers_count":122,"open_issues_count":0,"forks_count":38,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-03-29T07:04:20.074Z","etag":null,"topics":["threejs","webgl","webxr"],"latest_commit_sha":null,"homepage":"https://meta-quest.github.io/webxr-first-steps/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/meta-quest.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-22T05:35:31.000Z","updated_at":"2025-03-27T10:52:22.000Z","dependencies_parsed_at":"2024-11-07T11:00:38.438Z","dependency_job_id":"2f58c980-23ba-45b7-be27-75e95ef3d71e","html_url":"https://github.com/meta-quest/webxr-first-steps","commit_stats":null,"previous_names":["meta-quest/webxr-samples","meta-quest/spatial-web-template","meta-quest/webxr-first-steps","oculus-samples/webxr-first-steps"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meta-quest%2Fwebxr-first-steps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meta-quest%2Fwebxr-first-steps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meta-quest%2Fwebxr-first-steps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meta-quest%2Fwebxr-first-steps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/meta-quest","download_url":"https://codeload.github.com/meta-quest/webxr-first-steps/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247305932,"owners_count":20917208,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["threejs","webgl","webxr"],"created_at":"2024-09-24T19:59:25.594Z","updated_at":"2025-04-05T08:04:36.114Z","avatar_url":"https://github.com/meta-quest.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"./tutorial/assets/webxr-first-steps.png\" style=\"max-width:376px\"/\u003e\n\u003c/p\u003e\n\nWelcome 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](https://threejs.org/). 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.\n\n## What You’ll Build\n\nBy 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:\n\n\u003cfigure style=\"text-align: center;\"\u003e\n  \u003cimg src=\"./tutorial/assets/targetpractice.gif\" style=\"max-height:376px\"/\u003e\n  \u003cfigcaption\u003eTarget Practice Gameplay\u003c/figcaption\u003e\n\u003c/figure\u003e\n\n## Setting Up Your Local Development Environment\n\nTo prepare your development environment and get started with building your WebXR experience, follow the steps below:\n\n1. **Clone this repository**:\n\n   ```bash\n   git clone git@github.com:meta-quest/webxr-first-steps.git\n   cd webxr-first-steps\n   ```\n\n2. **Verify that you have Node.js and npm installed**:\n\n   - Node.js version: `20.x` or later\n   - npm version: `10.x` or later\n     You can check your versions with these commands:\n\n   ```bash\n   node -v\n   npm -v\n   ```\n\n3. **Install dependencies**:\n\n   ```bash\n   npm install\n   ```\n\n4. **Run the local development server**:\n\n   ```bash\n   npm run dev\n   ```\n\n   After running the above command, your development server will be available at `localhost:8081`.\n\n### Developing with a Headset\n\nYou 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.\n\n#### Accessing the Local Server on Your Headset via IP Address\n\nOn 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.\n\nFor example:\n\n```bash\n\u003ci\u003e [webpack-dev-server] Project is running at:\n\u003ci\u003e [webpack-dev-server] On Your Network (IPv4): https://192.168.0.123:8081/\n```\n\nYou 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.\n\n#### Accessing the Local Server on Your Headset via ADB\n\nIf accessing via IP address doesn’t work due to network restrictions or firewall settings, you can use **ADB (Android Debug Bridge)** and port forwarding:\n\n1. **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.\n2. **Set up port forwarding**: Open Chrome on your computer and navigate to `chrome://inspect/#devices`. Your headset should appear under **Remote Target**.\n\n3. **Configure port forwarding**:\n   - Click **Port forwarding...** in Chrome DevTools.\n   - Add a rule to forward port `8081` from your computer to your headset.\n\nYou 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.\n\n### Developing with an Emulator\n\nThis project includes a built-in emulation setup located in `./src/init.js`, powered by [IWER](https://github.com/meta-quest/immersive-web-emulation-runtime/) (Immersive Web Emulation Runtime) and [@iwer/devui](https://github.com/meta-quest/immersive-web-emulation-runtime/tree/main/devui). The emulation setup automatically detects native WebXR support in your browser and activates itself if no native WebXR support is found.\n\nIf you're already using the [Immersive Web Emulator browser extension](https://chromewebstore.google.com/detail/immersive-web-emulator/cgffilbpcibhmcfbgggfhfolhkfbhmik), 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.\n\n- **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.\n- 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.\n\nHere’s a showcase of the emulation setup in action:\n\n\u003cfigure style=\"text-align: center;\"\u003e\n  \u003cimg src=\"./tutorial/assets/iwerdevui.gif\" style=\"max-height:376px\"/\u003e\n  \u003cfigcaption\u003eIWER \u0026 IWER/DevUI Showcase\u003c/figcaption\u003e\n\u003c/figure\u003e\n\n## Getting Started\n\nThis 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.\n\n- [**Chapter 1: Creating Simple Objects**](./tutorial/chapter1.md): Learn how to add basic 3D shapes like cubes, spheres, and cones to your scene.\n- [**Chapter 2: Interacting with Controllers**](./tutorial/chapter2.md): Implement VR controller interactions and trigger actions based on user input.\n- [**Chapter 3: Animating Objects**](./tutorial/chapter3.md): Make bullets move in the direction of the controller, and learn about time-based animation in WebXR.\n- [**Chapter 4: Loading GLTF Models**](./tutorial/chapter4.md): Replace simple geometries with more complex, detailed 3D models using the GLTF format.\n- [**Chapter 5: Hit Detection and Score Tracking**](./tutorial/chapter5.md): Implement proximity-based hit detection, track player progress, and display scores.\n- [**Chapter 6: Finishing Touches**](./tutorial/chapter6.md): Add audio feedback, haptic feedback, and visual effects to make your game more immersive and polished.\n\nWe hope you enjoy working through the tutorial. Happy coding, and have fun building your WebXR game!\n\n## Build and Deploy\n\nOnce 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:\n\n### Deploying the App with GitHub Pages\n\nThis 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.\n\n#### Steps to Enable GitHub Pages Deployment:\n\n1. **Fork this repository** to your own GitHub account.\n2. Navigate to your forked repository’s **Settings**.\n3. Scroll down to the **Pages** section.\n4. Under **Build and Deployment**, change the **Source** to **GitHub Actions**.\n\nOnce 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.\n\nYou can monitor the status of the deployment job or manually re-run it via the **Actions** tab in your GitHub repository.\n\n### Deploying to Your Own Hosting Solution\n\nIf 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.\n\nTo generate the build, run the following command:\n\n```bash\nnpm run build\n```\n\nThis will create a `dist` folder containing the static files for the app. You can then upload these files to your hosting platform of choice.\n\n## Contributing\n\nPlease read [CONTRIBUTING.md](./CONTRIBUTING.md) for details on how to contribute to the project.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE.md](./LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeta-quest%2Fwebxr-first-steps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmeta-quest%2Fwebxr-first-steps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeta-quest%2Fwebxr-first-steps/lists"}