https://github.com/roydejong/beatsaberavatar.js

3D web viewer for Beat Saber multiplayer avatars (Three.js / WebGL).
https://github.com/roydejong/beatsaberavatar.js

3d avatar beatsaber threejs webgl

Last synced: about 1 month ago
JSON representation

3D web viewer for Beat Saber multiplayer avatars (Three.js / WebGL).

• Host: GitHub
• URL: https://github.com/roydejong/beatsaberavatar.js
• Owner: roydejong
• License: other
• Created: 2022-02-11T22:49:36.000Z (almost 3 years ago)
• Default Branch: main
• Last Pushed: 2022-03-20T04:22:47.000Z (almost 3 years ago)
• Last Synced: 2023-08-15T10:05:51.349Z (over 1 year ago)
• Topics: 3d, avatar, beatsaber, threejs, webgl
• Language: JavaScript
• Homepage:
• Size: 1.77 MB
• Stars: 6
• Watchers: 2
• Forks: 1
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE.md

Awesome Lists containing this project

README

        
# BeatSaberAvatar.js

**3D web viewer for Beat Saber multiplayer avatars (Three.js / WebGL).**

👀 **[Check out the Demo page](https://roydejong.github.io/BeatSaberAvatar.js/demo.html)**



    



## Installation

### Prebuilt

✅ You can download prebuilt releases from

the [GitHub releases page](https://github.com/roydejong/BeatSaberAvatar.js/releases/latest) ready for web use.

You'll need to host the `assets` folder in a publicly accessible location.

### Building from source

💀 You can build BeatSaberAvatar.js from source if you prefer.

Prerequisites: Node.js (v16 or newer).

1. Check out the source code

2. Install dependencies with `npm install`

3. Build using `npm run build`

For development, you can use `npm run watch` to get automatic builds on file changes.

## Usage

### Basic setup

Set up a target element on your page, and include the script. You can now use the `BeatSaberAvatar` global to access the

script's API and get started.

Here's a quick example that will present a random avatar:

```html

Placeholder content while loading


    window.addEventListener('load', function () {

        const renderTarget = document.getElementById('render-target');

        BeatSaberAvatar.setup(renderTarget); // returns renderer instance

    });

```

Because the script with Three.js is quite large, it's recommended to load it with `async` and `defer`. By then listening

to the `window.load` event you can be sure the script is ready to go.

### Setting avatar data

You can define avatar data by creating an instance of `BeatSaberAvatarData`.

You can pass this as the second argument of the `setup()` call, or later by calling `setAvatarData()` on the renderer

instance.

```js

// Example of complete avatar data

let avatarData = {

    "headTopId": "OnFire",

    "headTopPrimaryColor": "#a7966dff",

    "headTopSecondaryColor": "#900277ff",

    "glassesId": "Glasses01",

    "glassesColor": "#a7796dff",

    "facialHairId": "Moustache02",

    "facialHairColor": "#a7796dff",

    "handsId": "BareHands",

    "handsColor": "#a7796dff",

    "clothesId": "Hoodie",

    "clothesPrimaryColor": "#cf3384ff",

    "clothesSecondaryColor": "#4b2da5ff",

    "clothesDetailColor": "#000000ff",

    "skinColorId": "Default",

    "eyesId": "Eyes6",

    "mouthId": "Mouth12"

};

let instance = BeatSaberAvatar.setup(renderTarget, avatarData);

// Or, later:

instance.setAvatarData(avatarData);

```

If you don't provide avatar data or pass `null`, a random avatar will be presented instead.

### Advanced options

You can provide advanced options as the third parameter in the `setup` call:

```js

const options = {

    assetsBaseDir: "/static/avatar_assets/",

    enableControls: false,

    rotateAnimation: true

};

BeatSaberAvatar.setup(renderTarget, avatarData, options);

```

Here's an overview of the supported options:

| Key                | Default    | Description                                                                                                     |

|--------------------|------------|-----------------------------------------------------------------------------------------------------------------|

| `assetsBaseDir`    | `assets/`  | Base directory from which model and texture assets are loaded.                                                  |

| `enableControls`   | `true`     | Enable orbit camera controls.                                                                                   |

| `rotateAnimation`  | `true`     | If true, the avatar will slowly rotate from side to side.                                                       |

| `allowRandomize`   | `true`     | If true, missing or invalid parts will be randomized. If false, missing or invalid parts will not be rendered.  | 

| `enableGlasses`    | `false`    | If true, render glasses from avatar data (unused assets).                                                       |

| `enableFacialHair` | `false`    | If true, render facial hair from avatar data (unused assets).                                                   |

| `initialZoomLevel` | `1.5`      | Sets the initial zoom level of the camera (z-depth).                                                            | 

## License

This is a fan project for non-commercial purposes. Assets used in this project are unlicensed and are the property of

Beat Games.

The code in this repository is available under the MIT license.

For details, see [LICENSE](./LICENSE.md).