Immersions is an open-source JavaScript library for building immersive experiences in WebXR. Powered by the Babylon.js 3D engine, it runs seamlessly in browsers across desktop, mobile, and VR headsets.

The library is based on the idea that the web is the best foundation for building an open network of virtual experiences. It was originally developed in January 2021 as part of an immersive artistic platform. From the outset, the aim was to steer clear of commercial platforms as a means of artistic expression.

Since then, the project has seen major updates and grown into a library capable of powering anything from simple point-and-click games to cinematic 3D replays.

I continue to update the engine to meet my own artistic needs, and contributions from others are always welcome.

Features:

• Point and Click Navigation: create viewpoints, attach 3D exhibits, text and audio to tell your story.

• Collection system: collect items and unlock a completion state once a set number of items has been gathered.

• Cross-platform: works on most browsers - mobile, desktop and virtual reality headsets (tested on Meta Quest 2, 3 and Pico).

• Cinematic mode: automatically replay a scene with subtitles and camera animations.

• AI-ready: structured and documented so AI agents can generate and test scenes on their own.

• Open Source: you own and retain full control over your virtual space.

• Boundless: whether you are an artist, architect or designer, the only limit is your imagination.

👉 Explore mini art games built with Immersions

This library is available under the Apache-2.0 License and free to use. See NOTICE file for full attribution requirements.

1. Clone or download this repository into a folder alongside your own work:

   your-projects/
     immersion_engine/   ← this repo
     my-immersion/       ← your work (later)
   

2. Install a local web server — I use Python SimpleHTTPServer.
3. Start the server from your-projects/: python3 -m http.server 9000
4. Open the demo: localhost:9000/immersion_engine/examples/demo/index.html
5. Copy immersion_engine/examples/template/ into your-projects/ and rename it to start your own immersion.

Production note: the demo and template load BabylonJS from a CDN. For production deployments, replace the CDN <script> tags with local copies — this removes the network dependency and works fully offline.

Each immersion is a self-contained folder:

• index.html — loads BabylonJS, the engine files, your immersion class, then calls createImmersion(ClassName)
• [name].js — your immersion class extending Immersion
• [name].json — texts and stands data
• 3D assets (.glb, .obj, .gltf, .vrm, images, audio)

Immersions are composed of reusable navigation elements called stands. Stands let visitors interact with the scene from desktop, mobile, or VR. The engine handles the UI and navigation automatically so you can focus on your experience.

Stand types:

• Stand — basic viewpoint, no description
• Display — viewpoint with a title/description window and optional audio
• Plinth — Display with a 3D exhibit model
• Teleporter — teleports the visitor to another stand
• Link — opens an external URL

All stand types are demonstrated in examples/demo/.

Pass a mode URL parameter to change how the scene is rendered.

The engine includes characters/character.js, a helper for loading and animating humanoid characters in VRM format.

const character = new Character(scene, "/path/to/characters/", "slug.vrm");
await character.load();
character.root.position = new BABYLON.Vector3(0, 0, 0);
character.body("default").look("right").mouth("smiling");
character.startTalking();
character.stopTalking();

Here are some tips on how to easily create your digital assets.

• Keep an eye on total asset size — I recommend not exceeding 20Mb.
• For 3D models, the standard is Blender. I personally prefer creating models directly in VR using Gravity Sketch on the Meta Quest.
• For animations, I use Mixamo.
• For 3D scans, I use Polycam. Don't expect perfect results but it does the job.
• Free VRM characters can be found on Open Source Avatars.

Contributions are welcome. See CONTRIBUTING.md for setup instructions, code conventions, and how to run tests.