https://github.com/volumetrics-io/mrjs
An extensible WebComponents library for the Spatial Web
https://github.com/volumetrics-io/mrjs
immersive-web javascript mixedreality rapier3d spatialcomputing spatialweb threejs webcomponents
Last synced: 8 months ago
JSON representation
An extensible WebComponents library for the Spatial Web
- Host: GitHub
- URL: https://github.com/volumetrics-io/mrjs
- Owner: Volumetrics-io
- License: mit
- Created: 2023-04-18T06:16:42.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2024-10-11T05:48:25.000Z (over 1 year ago)
- Last Synced: 2025-04-12T01:05:04.390Z (about 1 year ago)
- Topics: immersive-web, javascript, mixedreality, rapier3d, spatialcomputing, spatialweb, threejs, webcomponents
- Language: JavaScript
- Homepage: https://mrjs.io
- Size: 97 MB
- Stars: 163
- Watchers: 3
- Forks: 8
- Open Issues: 102
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT
Awesome Lists containing this project
README
An extensible library of Web Components for the spatial web.
[](https://github.com/Volumetrics-io/mrjs/actions/workflows/build.yml) [](https://github.com/Volumetrics-io/mrjs/actions/workflows/test.yml) [](https://github.com/Volumetrics-io/mrjs/blob/main/LICENSE)
[](https://docs.mrjs.io) [](https://examples.mrjs.io)
## 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](https://github.com/mrdoob/three.js), the [Custom Elements API](https://developer.mozilla.org/en-US/docs/Web/API/Web_components), [Rapier.js](https://github.com/dimforge/rapier), and our own built-in ECS (Entity Component System) setup.
[[ECS - what is it?](https://docs.mrjs.io/ecs/what-is-it/)] - [[ECS - how we use it](https://docs.mrjs.io/ecs/how-we-use-it/)] - [[MRjs - Creating custom entities, components, && systems](https://docs.mrjs.io/ecs/how-we-use-it/#defining-custom-components--systems-in-mrjs)]
## Getting started
### Via HTML Script Tag:
For the latest stable version:
```html
…
…
```
For the daily build. No guarantee of stability:
```html
…
…
```
### Via NPM:
```sh
npm i mrjs
```
### Via Github Source:
1) [Clone this repository](https://github.com/Volumetrics-io/mrjs) ([github's how-to-clone](https://docs.github.com/en/get-started/getting-started-with-git/about-remote-repositories))
```sh
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:
> ```sh
> 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:
> ```sh
> git submodule update --init --recursive
> ```
2) Next, setup your node environment ([make sure node is setup properly](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)):
```sh
npm install
```
3) and now build:
```sh
npm run build
```
## Running the samples and tests
Note for in-headset testing / running of samples: [https requirement](#https-requirement)
### Samples
This only works if you're setting this up [via github source](#via-github-source); otherwise, go to [examples.mrjs.io](https://examples.mrjs.io) to try out the samples there.
You are able to try the samples locally and in headset by running the following:
```sh
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:
> ```sh
> npm run update-submodules
> ```
### Tests
```sh
npm run test
```
### Updating Documentation:
Check [docs.mrjs.io](https://docs.mrjs.io) or our [repository](https://github.com/Volumetrics-io/documentation) 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.
```sh
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](https://webpack.js.org/configuration/dev-server/) with `https: true`.
Here are some additional solutions:
- [Live Server](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer) for VS Code
- [via Python](https://anvileight.com/blog/posts/simple-python-http-server/)
Both options require you generate an SSL certificate and a key via OpenSSL:
```sh
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365
```