mmd-parser

library1.0.4jsnpmunverified

MMD Parser is a JavaScript library designed for parsing MMD (MikuMikuDance) data files, specifically PMD, PMX, VMD, and VPD formats. It takes ArrayBuffer or String inputs and outputs structured JavaScript objects representing the parsed model or motion data. The current stable version is 1.0.4, as indicated by the package metadata. This package serves as a low-level data interpreter for MMD assets, providing the raw data for applications that wish to display or manipulate MMD content programmatically, rather than being a renderer itself. Its primary function is to abstract the binary or text parsing of these complex 3D model and animation formats into easily consumable JavaScript objects. The library has been in a stable state, primarily focusing on parsing capabilities without frequent breaking changes or new feature additions, making it a reliable choice for integrating MMD data handling into JavaScript projects. It differentiates itself by focusing purely on parsing, leaving rendering and further processing to other libraries like Three.js.

serialization data

npm install mmd-parser

github ↗package ↗

INSTALL

IMPORT

SIG · MMD-PARSER

mmd-parser

serializationjavascriptv1.0.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Parser

✓ const { Parser } = require('mmd-parser');

✗ import { Parser } from 'mmd-parser';

The library primarily uses CommonJS `require` syntax. Direct ESM `import` is not supported without a transpiler or bundler.

MMDParser.Parser (global/namespace)

✓ const MMDParser = require('mmd-parser'); const parser = new MMDParser.Parser();

✗ const parser = new require('mmd-parser').Parser();

This pattern mimics the browser's global `MMDParser` object, where `Parser` is a property on it. It's less common in modern Node.js but semantically equivalent to destructuring.

MMDParser (browser global)

✓ <script src="./build/mmdparser.js"></script> <script> var parser = new MMDParser.Parser(); </script>

In browser environments, `MMDParser` is exposed as a global object when the script is included directly.

Demonstrates how to instantiate the MMD Parser and attempt to parse simulated PMD and PMX ArrayBuffer data in a Node.js environment.

const { Parser } = require('mmd-parser'); const parser = new Parser(); // Simulate loading a PMD file as an ArrayBuffer // In a real application, you would load this from disk or network. // This is a minimal dummy buffer, a real PMD file is much larger. // A PMD file structure starts with a header, for example, "Pmd" magic string. const dummyPmdBuffer = new ArrayBuffer(50); const view = new DataView(dummyPmdBuffer); // Write 'P', 'm', 'd' magic bytes (ASCII codes 80, 109, 100) view.setUint8(0, 80); view.setUint8(1, 109); view.setUint8(2, 100); // Try parsing the dummy PMD buffer try { const pmdData = parser.parsePmd(dummyPmdBuffer, false); // false for right-handed coordinates console.log('Successfully parsed dummy PMD header:'); // A real PMD object would have many properties, e.g., metadata, bones, faces, etc. console.log('PMD header data:', pmdData.header); } catch (error) { console.error('Error parsing PMD data:', error.message); console.warn('Note: This is a dummy buffer and not a real PMD file, so parsing will likely fail or return incomplete data.'); } // Example of parsing a dummy PMX buffer const dummyPmxBuffer = new ArrayBuffer(50); const pmxView = new DataView(dummyPmxBuffer); pmxView.setUint8(0, 80); pmxView.setUint8(1, 77); pmxView.setUint8(2, 88); pmxView.setUint8(3, 32); // ' PMX ' try { const pmxData = parser.parsePmx(dummyPmxBuffer, false); console.log('\nSuccessfully parsed dummy PMX header:'); console.log('PMX header data:', pmxData.header); } catch (error) { console.error('Error parsing PMX data:', error.message); console.warn('Note: This is a dummy buffer and not a real PMX file, so parsing will likely fail or return incomplete data.'); }

Debug

Known issues

gotchaThe library `mmd-parser` is a CommonJS (CJS) module. Attempting to use `import { Parser } from 'mmd-parser';` directly in an ESM context will result in a runtime error unless a bundler or Node.js's `--experimental-json-modules` flag (or similar mechanism) is used.

fix

For CommonJS, use `const { Parser } = require('mmd-parser');`. For ESM projects, if you must use it directly, consider a dynamic import `import('mmd-parser').then(({ Parser }) => { /* ... */ });` or configure your build tools (e.g., Webpack, Rollup) to handle CJS imports.

affects: >=1.0.0

gotchaWhen using the parsed MMD data, especially for Vocaloid characters like Hatsune Miku, Kagamine Rin, etc., it is crucial to adhere to the usage guidelines set by Crypton Future Media, INC. Failure to do so may lead to copyright infringement. The library itself handles parsing, but the user is responsible for the legal use of the output data.

fix

Always review http://piapro.net/en_for_creators.html or the latest guidelines from Crypton Future Media, INC. before distributing or publicly using content derived from MMD assets.

affects: >=1.0.0

gotchaThe parser functions (`parsePmd`, `parsePmx`, `parseVmd`) expect an `ArrayBuffer` as the first argument, while `parseVpd` expects a `string`. Providing the wrong type of input will lead to parsing errors or unexpected behavior, often without explicit type checking failures at compile time in pure JavaScript.

fix

Ensure the input data is correctly read into an `ArrayBuffer` for binary formats (PMD, PMX, VMD) and a `string` for text formats (VPD) before passing it to the respective parser method.

affects: >=1.0.0

gotchaThe library primarily focuses on parsing the MMD data into a structured JavaScript object. It does *not* provide any rendering capabilities. Users must integrate the parsed data with a 3D rendering library (e.g., Three.js) to visualize MMD models and animations.

fix

Be aware that `mmd-parser` is a data-processing utility. To display models, integrate its output with a 3D graphics framework. The parsed object contains vertex data, bone information, textures, animations, etc., which need to be passed to a renderer's scene graph.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'Parser')

Attempting to access `Parser` on an undefined or incorrectly imported `mmd-parser` module, commonly seen when mixing CJS `require` with incorrect destructuring or expecting a default export that doesn't exist.

fix

Ensure `mmd-parser` is correctly imported. Use `const { Parser } = require('mmd-parser');` for CommonJS or `const MMDParser = require('mmd-parser'); const parser = new MMDParser.Parser();` to mimic global access.

Error: Not a PMD file.

The `parsePmd` method was called with an `ArrayBuffer` that does not start with the expected 'Pmd' magic string, indicating either a corrupt file, an incorrect file format (e.g., PMX or VMD passed to `parsePmd`), or a non-ArrayBuffer input.

fix

Verify that the input `ArrayBuffer` corresponds to a valid PMD file. Check the file's integrity and ensure you are using the correct parsing method (e.g., `parsePmx` for PMX files, `parseVmd` for VMD files).

TypeError: Cannot convert undefined or null to object

This error often occurs when a parser function receives `null` or `undefined` instead of an `ArrayBuffer` or `string`, typically due to a failed file load operation or incorrect data handling before passing to the parser.

fix

Before calling a parser method, always validate that the `ArrayBuffer` or `string` input is properly loaded and is not `null` or `undefined`.

Upgrade

Version history

1.0.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

28 hits · last 30 days

node

Bingbot

Resources

githubhttps://github.com/takahirox/mmd-parser ↗

packagehttps://www.npmjs.com/package/mmd-parser ↗