@pmx-three/core

无运行时依赖的 PMX 2.x 二进制解析器。

安装

npm install @pmx-three/core

基本用法

浏览器

import { parsePmx } from '@pmx-three/core';

const response = await fetch('/models/character.pmx');
if (!response.ok) throw new Error(`Request failed: ${response.status}`);

const pmx = parsePmx(await response.arrayBuffer());
console.log(pmx.metadata.name, pmx.vertices.length);

Node.js

Node.js 的 Buffer 可能只是底层 ArrayBuffer 的一个切片，传入前需保留正确的字节范围：

import { readFile } from 'node:fs/promises';
import { parsePmx } from '@pmx-three/core';

const bytes = await readFile('./character.pmx');
const buffer = bytes.buffer.slice(
  bytes.byteOffset,
  bytes.byteOffset + bytes.byteLength,
);
const pmx = parsePmx(buffer);

解析与校验

parsePmx 负责二进制格式解析：

import { parsePmx, PmxParseError } from '@pmx-three/core';

try {
  const model = parsePmx(buffer);
} catch (error) {
  if (error instanceof PmxParseError) {
    console.error(error.section); // 例如 "vertices"
    console.error(error.offset);  // 失败位置的字节偏移
  }
  throw error;
}

validatePmx 对已经解析的模型执行跨字段与索引引用检查：

import { parsePmx, validatePmx } from '@pmx-three/core';

const model = parsePmx(buffer);
const issues = validatePmx(model);
const errors = issues.filter((issue) => issue.severity === 'error');

for (const issue of issues) {
  console.warn(issue.code, issue.section, issue.itemIndex, issue.message);
}

也可以用 parsePmxWithDiagnostics(buffer) 一次获得 { model, issues }。二进制本身无法解析时，该函数仍会抛出 PmxParseError；issues 只表示成功解析后的结构校验结果。

API

| 导出 | 说明 | | --- | --- | | parsePmx(buffer) | 将 PMX 2.0/2.1 二进制数据解析为 PmxModel | | parsePmxWithDiagnostics(buffer) | 解析模型并调用 validatePmx | | validatePmx(model) | 返回 PmxValidationIssue[]，检查索引、材质覆盖范围与部分 PMX 版本约束 | | PmxParseError | 包含 section 与 offset 的解析异常 | | PmxBinaryReader | PMX 小端二进制读取器，供高级用法或扩展解析使用 | | PmxModel 及相关类型 | 完整的 TypeScript 数据结构定义 |

支持范围

• PMX 2.0、2.1
• UTF-16LE、UTF-8
• BDEF1、BDEF2、BDEF4、SDEF、QDEF
• group、vertex、bone、UV、material、flip、impulse morph
• 刚体、关节，以及 PMX 2.1 软体数据

License

MIT