[2026/8/6]

[WEB App] PMX Checker - PMXファイルのチェック＆修復ツール

[WEB App] PMX Checker - PMXファイルのチェック＆修復ツール

概要

PMX（MikuMikuDance モデルフォーマット）ファイルのバイナリを直接パースし、ボーン構造やインデックス参照の整合性を網羅的に検証するWebツール。 アップロード不要で、ファイルはローカル環境（ブラウザ内）で処理され、外部サーバーには送信されません。

特定のPMXモデルをThree.jsのMMDAnimationHelperで使用した際、GrantSolverがundefined.quaternionでクラッシュする問題の原因調査から生まれたツールです。

🔗 ツールを開く: PMX Checker

開発の経緯

Lain Clock にYYB式初音ミク（748ボーン）を読み込んだ際、以下のエラーが発生しました。

Uncaught TypeError: Cannot read properties of undefined (reading 'quaternion')
    at GrantSolver.updateOne (MMDAnimationHelper.js:1185:45)

「PMXファイルが壊れている」という仮説のもとチェックツールを開発しましたが、結果はclean。真の原因はThree.jsのMMDLoaderがランタイムで構築するskeleton.bones配列とPMXのボーンインデックスのズレでした。

詳細は以下の記事で解説しています。

PMXファイル自体の検証ツールとしては汎用的に使えるため、独立したツールとして公開しています。

使い方

1. PMXファイルを読み込む

画面左の「INPUT」エリアからファイルを読み込む。

  • ドラッグ＆ドロップ — PMXファイルまたはPMXを含むZIPファイルを破線エリアにドロップ
  • クリックで選択 — エリアをクリックしてファイル選択ダイアログから選ぶ

ZIP形式の場合、ZIP内のPMXファイルを自動的に検出・展開します（Shift_JISファイル名にも対応）。

PMX Checker - PMXファイルのチェック＆修復ツール ( 1. PMXファイルを読み込む )

2. 診断結果の確認

読み込みが完了すると、即座にバイナリパースと全項目のチェックが実行されます。

左パネルの FILE INFO セクションにファイル情報が表示されます。

項目内容
Fileファイル名
VersionPMXバージョン（2.0 / 2.1）
Encoding文字エンコーディング（UTF-16LE / UTF-8）
Modelモデル名
Vertices頂点数
Faces面（三角形）数
Texturesテクスチャ数
Materialsマテリアル数
Bonesボーン数
Morphsモーフ数
Rigid Bodies剛体数
Jointsジョイント数

右パネルの DIAGNOSTICS に検証ログがリアルタイムで出力されます。

  • 🟢 緑 — チェックパス
  • 🟡 黄 — 警告（動作に影響する可能性）
  • 🔴 赤 — エラー（クラッシュの原因になる）
  • 🔵 青 — 自動修復可能な項目
PMX Checker - PMXファイルのチェック＆修復ツール ( 2. 診断結果の確認 )

3. 修復とダウンロード

付与親（Grant Parent）の不正参照が検出された場合、⚡ REPAIR & DOWNLOAD ボタンが有効になります。

修復処理の内容は以下の通りです。

  • 不正な付与親インデックスを -1（無効）に書き換え
  • 対応する付与率を 0.0 にリセット
  • 修復後に再検証を実行し、修復の成功を確認

ZIP入力の場合はZIPに再パッケージ、PMX単体の場合はPMXファイルとしてダウンロードされます。

チェック項目一覧

ヘッダー

チェック内容
マジックPMX シグネチャの検証
バージョンPMX 2.0 / 2.1 の範囲チェック
グローバル設定インデックスサイズ・エンコーディングの妥当性

ボーン構造（最重要）

チェック内容
親ボーンインデックス範囲外参照・自己参照の検出
付与親（Grant Parent）範囲外参照・自己参照・循環ループの検出（GrantSolverクラッシュの直接原因）
表示先ボーン範囲外参照の検出
IKターゲット範囲外参照の検出
IKリンク範囲外参照の検出

頂点

チェック内容
ボーンインデックスBDEF1/2/4・SDEF・QDEFの参照先が有効範囲内か
ウェイトタイプ不明なウェイトタイプの検出

マテリアル

チェック内容
テクスチャインデックス範囲外参照の検出
スフィアテクスチャ範囲外参照の検出
面数合計全マテリアルの面数合計と面インデックス数の整合性

面インデックス

チェック内容
頂点インデックス範囲外参照の検出

剛体・ジョイント

チェック内容
剛体のボーン参照範囲外参照の検出
ジョイントの剛体参照範囲外参照の検出

修復のしくみ

修復対象は 付与親（Grant Parent）の不正参照 に限定しています。

PMXバイナリのボーンセクション内で、付与フラグ（0x0100 回転付与 / 0x0200 移動付与）が立っているボーンの付与親インデックスを直接バイナリパッチします。

修復前: [付与親インデックス = 9999] [付与率 = 0.85]
修復後: [付与親インデックス = -1  ] [付与率 = 0.0 ]

ファイル全体の構造（オフセット・サイズ）は変更しないため、他のセクションへの影響はありません。

修復後は自動的に再検証が実行され、修復の成功を確認した上でダウンロードが開始されます。

関連ツール

ツール用途
VRM to MMDVRMモデルをPMX形式に変換
MMD to GLBPMX + VMDからアニメーション付きGLBを生成
VRM ValidatorVRMファイルのバリデーション
VRM OptimizerVRMモデルのWebP + Draco圧縮
VRM Texture ReplacerVRMテクスチャの確認・差し替え

技術仕様

項目内容
PMXパース独自実装バイナリリーダー（DataView）
対応バージョンPMX 2.0 / 2.1
対応エンコーディングUTF-16LE / UTF-8
修復方式バイナリパッチ（構造非破壊）
ZIP処理JSZip（Shift_JISファイル名対応）
フレームワークAstro
データ処理全てブラウザ内、サーバー通信なし

対応ブラウザ

WebGL対応のモダンブラウザ（Chrome / Edge / Firefox / Safari）。 バイナリパースを伴うため、大規模モデル（ボーン数500以上）の処理にはPC環境での利用を推奨。

利用上の注意

  • 修復機能は付与親（Grant Parent）の不正参照のみを対象としています。ボーン親の循環参照やIKの構造的な問題は手動修正（PMXエディタ等）が必要です
  • MMDモデルの利用にあたっては、各データの利用規約を遵守してください