mrjs

v0.6.4

Published

2 years ago

an MR first webXR framework

Downloads

0High
0Medium
0Low

hanbollar

lobau

michaelthatsit

An extensible library of Web Components for the spatial web.

Branches

Large refactor of MRjs happening on branch, stay tuned!
branch still being used for dependabots and quick fix cleanups

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:

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

Next, setup your node environment (make sure node is setup properly):

npm install

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:

Live Server for VS Code
via Python

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