
## **[babylon-mmd](https://github.com/noname0310/babylon-mmd)**: The MMD Loader and Runtime for Babylon.js

![Screenshot showing the MMD model in the playground](/img/extensions/mmdLoader/ModelWithInspector.png)
*[YYB Hatsune Miku_10th](https://www.deviantart.com/sanmuyyb/art/YYB-Hatsune-Miku-10th-DL-702119716) by YYB (modified)*

MMD is a Japanese 3D animation creation software that has its own 3D model format, PMD/PMX, and motion formats, VPD and VMD.

babylon-mmd is a library focused on loading PMX models and VMD motion files into babylon js and playing high-quality dance animations.

## Features

- Load PMX models and VMD motion files
- Solve IK, AppendTransform(a.k.a. Append, Grant) and RigidBody / Joint simulation
- MMD morph system
- MmdStandardMaterial for PMX models
- Support multiple models and motions
- Synced audio playback
- Player controls (play, pause, etc.)
- Optimized custom format for MMD models and motions

## Example

![Playground example of a MMD](/img/extensions/mmdLoader/PGScreenshot.png)
<Playground id="#028YR6#1" title="Complete MMD Example" description="Example of a MMD model with a VMD motion file and audio." />

*Music: [メランコリ・ナイト](https://youtu.be/y__uZETTuL8) by higma*

*Model: [YYB Hatsune Miku_10th](https://www.deviantart.com/sanmuyyb/art/YYB-Hatsune-Miku-10th-DL-702119716) by YYB (modified)*

*Motion / Camera: https://www.nicovideo.jp/watch/sm41164308 by ほうき堂*

## Usage

These are just a few code snippets, please refer to the documentation for full usage

### Installation

ES6 module:

```bash
npm add @babylonjs/core @babylonjs/havok babylon-mmd
```

UMD module using the html script tag:

```html
<script src="https://cdn.babylonjs.com/babylon.js"></script>
<script src="https://cdn.babylonjs.com/havok/HavokPhysics_umd.js"></script>
<script src="https://www.unpkg.com/babylon-mmd/umd/babylon.mmd.min.js"></script>
```

UMD module in Playgrounds:

```typescript
declare const BABYLONMMD: any;

await new Promise((resolve) => {
    const babylonMmdScript = document.createElement("script");
    babylonMmdScript.src = "https://www.unpkg.com/babylon-mmd/umd/babylon.mmd.min.js";
    document.head.appendChild(babylonMmdScript);
    babylonMmdScript.onload = resolve;
});
```

### Import PMX Model

<Playground id="#FY1L15" title="Import PMX Model" description="Example of importing a PMX model." />

```typescript
import "babylon-mmd/esm/Loader/pmxLoader"; // side effect import

const mmdMesh = await SceneLoader.ImportMeshAsync(undefined, "your_model_path.pmx", undefined, scene).then((result) => result.meshes[0]);
```

load PMX model by `SceneLoader.ImportMeshAsync` always returns a 1-length array, so you can get the mesh by `result.meshes[0]`.

### Import VMD Motion

```typescript
const vmdLoader = new VmdLoader(scene);
const modelMotion = await vmdLoader.loadAsync("model_motion_1", "your_model_motion_path.vmd");
```

### Play MMD Animation

```typescript
const mmdRuntime = new MmdRuntime();
mmdRuntime.register(scene);
const mmdModel = mmdRuntime.createMmdModel(mmdMesh);
mmdModel.addAnimation(modelMotion);
mmdModel.setAnimation("model_motion_1");
```

## Documentation

In **[this document](https://noname0310.github.io/babylon-mmd/)**, you'll learn how to fully utilize babylon-mmd by creating two pieces of work together.



## TextureCanvas

![Fur material high](/img/extensions/texturecanvas.jpg)

## About

TextureCanvas is a texture on which other textures can be drawn.

NOTE - Texture Canvas works with Babylon.js 4.2 and below.

## Usage

## Creating a canvas

To construct a TextureCanvas, you need to provide the size and the scene the texture will be used in:

```javascript
// A square texture
let canvas = new TextureCanvas(128, scene);
```

```javascript
// A rectangular texture
let canvas = new TextureCanvas({ width: 256, height: 128 }, scene);
```

Aditionally, you may pass three more parameters, which are:

-   _initTexture_, an initial texture to draw.
-   _onReady_, a function to be called when the canvas is ready.
-   _options_, an object with the properties _generateMipMaps_ (boolean) and _samplingMode_ (number)

PG: <Playground id="#9S5YZY#6" title="Texture Canvas" description="Example of a TextureCanavas"/>

## Draw using contexts

Contexts can be used to specify how a texture should be drawn. Multiple contexts can be created and used interchangably.

To draw a texture using the default context, you can call `canvas.drawTexture(myTexture)`.

You can create a context like this:

```javascript
let ctx = canvas.createContext();
```

A context has the following propteries:

| Name                    | Type                                                                                                                | Description                                                                                               |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| diffuseTexture          | [Texture](/typedoc/classes/babylon.texture)                                                    | The texture to draw.                                                                                      |
| diffuseSamplingRect     | [Rectangle](https://github.com/Poolminer/BabylonTextureCanvas/blob/master/DOCUMENTATION.md#rectangle-class)         | The area of the diffuse texture to draw.                                                                  |
| drawRect                | [Rectangle](https://github.com/Poolminer/BabylonTextureCanvas/blob/master/DOCUMENTATION.md#rectangle-class)         | The area to draw to.                                                                                      |
| rotation                | [Vector3Matrix](https://github.com/Poolminer/BabylonTextureCanvas/blob/master/DOCUMENTATION.md#vector3matrix-class) | The rotation axes in radians to rotate the diffuse textures by (_z_ is 2D rotation).                      |
| pivotPoint              | [PivotPoint](https://github.com/Poolminer/BabylonTextureCanvas/blob/master/DOCUMENTATION.md#pivotpoint-class)       | The rotation pivot point.                                                                                 |
| skewing                 | [UVector](https://github.com/Poolminer/BabylonTextureCanvas/blob/master/DOCUMENTATION.md#uvector-class)             | The amount of skewing/shearing.                                                                           |
| opacityTexture          | [Texture](/typedoc/classes/babylon.texture)                                                    | The texture to get the alpha values from.                                                                 |
| opacityTextureIntensity | number                                                                                                              | How much the opacity texture should be contributing to the difuse's alpha values, ranging from 0.0 to 1.0 |
| opacitySamplingRect     | [Rectangle](https://github.com/Poolminer/BabylonTextureCanvas/blob/master/DOCUMENTATION.md#rectangle-class)         | The area of the opacity texture to use.                                                                   |
| clearColor              | [Color4](/typedoc/classes/babylon.color4)                                                      | The color to clear the canvas with.                                                                       |

And the following methods:

| Name                   | Parameters                                                                                         | Description                                                                                 |
| ---------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| reset                  |                                                                                                    | Resets the draw options to their default values.                                            |
| setDiffuseSamplingRect | u, v, width, height                                                                                | Sets which area of the diffuse texture to draw.                                             |
| setOpacitySamplingRect | u, v, width, height                                                                                | Sets which area of the opacity texture to draw.                                             |
| setDrawRect            | u, v, width, height                                                                                | Sets which area of the canvas to draw to — this area may be tranformed by rotating/skewing. |
| setRotation            | x?: number, y?: number, z?: number                                                                 | Sets the rotation axes in radians rotate the diffuse texture by (_z_ is 2D rotation).       |
| setPivotPoint          | pu?: number, pv?: number, isLocalSpace?: boolean                                                   | Sets the point around which to rotate the texture.                                          |
| setSkewing             | u, v                                                                                               | Sets how the texture should be skewed (shear transform).                                    |
| draw                   |                                                                                                    | Draws the diffuse texture, if set.                                                          |
| drawTexture            | diffuseTexture: Texture                                                                            | Draws a texture.                                                                            |
| clear                  |                                                                                                    | Clears the canvas using the set clearColor.                                                 |
| clone                  | cloneDrawOptions?:&nbsp;boolean, cloneTextures?:&nbsp;boolean, ref?:&nbsp;TextureCanvasDrawContext | Returns a clone of the context.                                                             |

Once the context is set up, simply call `ctx.draw()` or `ctx.drawTexture(myTexture)`

PG: <Playground id="#436DIW#2" title="Texture Canvas" description="Example of drawing on a TextureCanavas"/>

## Notes

Please note that uv-coordinates are used rather than pixel values.

## Rotation

Rotating a texture happens in three dimensions in the default coordinate system of Babylon.js, with _z_ being the forward axis.

You can set a pivot point to be in local space (that of the diffuse texture), or world space (that of the canvas), with `pivotPoint.isLocalSpace`.



Generate letters in BABYLON meshes.

## Basic-Usage

```javascript
Writer = BABYLON.MeshWriter(scene, { scale: scale });
text1 = new Writer("ABC", {
  anchor: "center",
  "letter-height": 50,
  color: "#1C3870",
  position: {
    z: 20,
  },
});
```

PG: <Playground id="#PL752W#150" title="Mesh Writer Example 1" description=""/>

## Getting the code

Copy https://github.com/BabylonJS/Extensions/blob/master/MeshWriter/meshwriter.min.js or https://github.com/BabylonJS/Extensions/blob/master/MeshWriter/meshwriter.js and build it into your load sequence.

## If you prefer npm

### npm i meshwriter

Import in your React/Angular component:

`import { MeshWriter } from "meshwriter";`

With **meshwriter** you can use MeshWriter directly like this:

```javascript
let Writer = MeshWriter(this.scene, { scale: 0.25, defaultFont: "Arial" });
let textMesh = new Writer("Hello World", {
  "font-family": "Arial",
  "letter-height": 30,
  "letter-thickness": 12,
  color: "#1C3870",
  anchor: "center",
  colors: {
    diffuse: "#F0F0F0",
    specular: "#000000",
    ambient: "#F0F0F0",
    emissive: "#ff00f0",
  },
  position: {
    x: 0,
    y: 10,
    z: 0,
  },
});
```

## Superconstructor - BABYLON.MeshWriter()

After MeshWriter is loaded, BABYLON.MeshWriter is defined. It is called with one or two parameters.

- **scene** &nbsp; required
- **preferences** &nbsp; optional &nbsp; The preferences object may specify up to three values

        FIELD                 DEFAULT
      default-font           Helvetica
      scale                      1
      letter-origin         "letter-center"

The call to BABYLON.MeshWriter returns a constructor. Call it "**Writer**".

## Constructor - new Writer()

new Writer() is called with a string and an (optional) options parameter.&nbsp; The options object conforms to normalBabylon.js structures and terminology.

          FIELD                 DEFAULT
        font-family             default-font
        anchor                  left
        letter-height           100
        letter-thickness        1
        color                   #808080              # hits emissive only
        alpha                   1
        position
            x                   0
            y                   0
            z                   0
        colors                                       # if you need to control more than just emissive
            diffuse             #F0F0F0
            specular            #000000
            ambient             #F0F0F0
            emissive            color                # from option field 'color' above

**new Writer()** builds a mesh with material that is inserted into the scene.&nbsp; This is a multi-step process with interim meshes and holes per letter.&nbsp; These meshes are sucked into an SPS and then disposed.&nbsp; At the end, one mesh, one material and one SPS have been added to the scene.

**new Writer()** also returns a **writer** instance with useful methods.&nbsp; See below.

## Instance

Each **writer** instance has methods to allow one to retrieve theBabylon.js objects or to get/set attributes of the SPS.

       getSPS
       getMesh
       getMaterial
       color                   # sets or gets color but no change to material
       alpha                   # sets or gets alpha but no change to material
       setColor                # set emissive color and change color value
       setAlpha                # change value and material
       overrideOpac            # change material but not value
       resetOpac               # sets material to current value
       dispose

## Usage Hints

If you wish to do extensive things with position, rotation or animation, retrieve the meshes and materials from the instance using the methods shown above.&nbsp; The output from **new Writer()** is an SPS with one particle for each character.

Example:
PG: <Playground id="#PL752W#151" title="Mesh Writer Example 2" description=""/>

```javascript
const SCALE = 0.25;
const TEXT_SIZE = 35;
const TEXT_THICKNESS = 10;

Writer = BABYLON.MeshWriter(scene, { scale: SCALE, defaultFont: "Arial" });
textMesh = new Writer("BABYLON JS", {
  "font-family": "Arial",
  anchor: "center",
  "letter-height": TEXT_SIZE,
  "letter-thickness": TEXT_THICKNESS,
  color: "#1C3870",
  colors: {
    diffuse: "#F0F0F0",
    specular: "#000000",
    ambient: "#F0F0F0",
    emissive: "#ff00f0",
  },
  position: {
    x: 0,
    y: 5,
    z: 70,
  },
});

//Text Writer create SPS with Particle for each letter
SPS = textMesh.getSPS();

//Update animation
SPS.updateParticle = (particle) => {
  particle.rotation.x -= 0.06;
};

scene.registerBeforeRender(() => {
  SPS.setParticles();
  //sps.mesh.rotation.y = k;
});
```

Colors:&nbsp; With most lighting, it is enough just to use the "color" field to specify the letter coloring.&nbsp; However, programmers may specify all four color types by putting a "colors" object in the options object.

Unless you have a specific need, do not specify a font.&nbsp; The default font, Helvetica, has the most extensive characters and the fewest faces; it will be the most efficient if you have a lot of text.&nbsp; Jura was added because the author likes it for numbers.


MMD Loader

babylon-mmd: The MMD Loader and Runtime for Babylon.js

Features

Example

Usage

Installation

Import PMX Model

Import VMD Motion

Play MMD Animation

Documentation