The MRjs logo, an indigo and purple bowtie.

An extensible library of Web Components for the spatial web.

npm run build npm run test License: MIT

docs dev-examples

Branches

Overview

MRjs is a mixed-reality-first, WebXR user interface library meant to bootstrap spatial web development. It implements much of the foundational work so that developers can spend less time on the basics and more time on their app.

Designed to be extensible, MRjs provides a familiar interface via THREE.js, the Custom Elements API, Rapier.js, and our own built-in ECS (Entity Component System) setup.

[ECS - what is it?] - [ECS - how we use it] - [MRjs - Creating custom entities, components, && systems]

Getting started

Via HTML Script Tag:

For the latest stable version:

<head>
    …
    <script src="https://cdn.jsdelivr.net/npm/mrjs@latest/dist/mr.js"></script>
    …
</head>

For the daily build. No guarantee of stability:

<head>
    …
    <script src="https://cdn.jsdelivr.net/gh/volumetrics-io/mrjs/dist/mr.js"></script>
    …
</head>

Via NPM:

npm i mrjs

Via Github Source:

  1. Clone this repository (github’s how-to-clone)
git clone the.cloning.url

If you are planning to contribute to this repo instead of just using is as a source you will need its submodules for proper samples and testing:

git clone --recurse-submodules the.cloning.url

If you’ve already cloned the repo the normal way (git clone the.cloning.url) you can update for the submodule as follows:

git submodule update --init --recursive
  1. Next, setup your node environment (make sure node is setup properly):
npm install
  1. and now build:
npm run build

Running the samples and tests

Note for in-headset testing / running of samples: https requirement

Samples

This only works if you’re setting this up via github source; otherwise, go to examples.mrjs.io to try out the samples there.

You are able to try the samples locally and in headset by running the following:

npm run server

We serve some of our examples and testing files from submodules, if you are planning to contribute, there will be times when the submodule for your work might be out of date. Since we run scripts along with our submodule update. Run the following to stay up to date:

npm run update-submodules

Tests

npm run test

Updating Documentation:

Check docs.mrjs.io or our repository for the full documentation.

For local documentation or to check the local output when writing your own PR to see how it will update, run the below command.

Note: the order of creation of docs depends on your operating system, so if when you run this and the order looks different, do not worry - in the repository itself our action will handle that for you and default to use the right version for these automatically generated docs.

npm run docs

HTTPS Requirement

To test in headset, WebXR requires that your project be served using an HTTPS server. If you’re using Webpack, you can achieve this by utilizing the Dev Server webpack plugin with https: true.

Here are some additional solutions:

Both options require you generate an SSL certificate and a key via OpenSSL:

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365
Suggest an edit on GitHub for README.md