Vibrant Visuals Material Toolkit

Blockbenchデスクトップ版5.1.0〜5.1.6向けの、Minecraft Bedrock Edition Vibrant Visuals用Material Zone編集プラグインです。主検証対象はBlockbench 5.1.6です。

Color Textureを変更せず、ピクセルごとのMaterial Zone所有情報を.bbmodel内のTextureプロパティへ保存します。ZoneからColor Alpha、MER（Metalness / Emissive / Roughness）、MERS（Metalness / Emissive / Roughness / Subsurface）とtexture_set.jsonを生成できます。

インストール

1. このディレクトリでnpm installを実行します
2. npm run packageを実行します
3. Blockbenchの「ファイル」→「プラグイン」→「ファイルからプラグインを読み込む」でdist/vibrant_visuals_material_toolkit.jsを選択します

開発時のコマンドは次のとおりです。

npm run check    TypeScript型検査
npm test         コア単体テスト
npm run build    Blockbench用単一JSを生成
npm run smoke    生成物の登録情報を検査
npm run package  上記を順番に実行

基本操作

1. Color Textureを選択し、「Vibrant Visuals Material Toolkit」Panelを開きます
2. ＋でMaterial Zoneを作成します
3. Opacity、Metalness、Emissive、Roughness、Subsurfaceを0〜255で設定します
4. ブラシまたは消しゴムを選び、Panel内の2D Canvasへ描画します
5. 必要に応じて2D表示チャンネルを切り替えます
6. 「標準Material Previewへ反映」または「texture_setを書き出す」を実行します

ブラシは円形ハードブラシです。Pointer間を線分補間するため、速く描いてもマスクが途切れにくくなっています。重なったピクセルは最後に描いたZoneが所有します。消しゴムは未割当へ戻します。Zone削除時もそのZoneの所有ピクセルは未割当へ戻ります。

Canvasの「Zoneマスク」を有効にすると、選択中Zoneは黄色、他のZoneはそれぞれ異なる色で元Texture上へ重ねて表示します。Pointer位置にはブラシ輪郭とX / Yピクセル座標をリアルタイム表示します。正確なColorやMER / MERSを確認するときは「Zoneマスク」を無効にしてください。

Canvas上でCtrl＋マウスホイールを操作すると、Pointer位置を基準に25%〜1600%で拡大縮小できます。座標表示横の倍率ボタンを押すと100%へ戻ります。ブラシサイズ1は、表示倍率に関係なく必ずTextureの1ピクセルだけを塗ります。

追加、削除、名前変更、各数値変更、ブラシ1ストローク、標準PBR反映は、それぞれ1回のUndo / Redo操作として記録されます。

Alpha・MER・MERS

Color Alphaには2つのモードがあります。

• 元Alphaを使用: 全ピクセルでColor Textureの現在のAlphaを使用します
• Zone Alphaで上書き: Zone割当済みピクセルだけZoneのOpacityを使用し、未割当は元Alphaを使用します

MERのチャンネルはR=Metalness, G=Emissive, B=Roughnessです。MERSは同じRGBにA=Subsurfaceを追加します。MERS AlphaのSubsurfaceはColor Alphaとは別データです。MERS Combined表示でも混同を避けるため、MER RGBとSubsurfaceを別ペインに表示します。

未割当ピクセルはMetalness 0、Emissive 0、Roughness 255、Subsurface 0になります。

出力ファイルは次の構成です。

model.png
model_mer.png                 MER選択時
model_mers.png                MERS選択時
model.texture_set.json

MERのtexture_set.jsonはformat_version: 1.16.100、MERSはformat_version: 1.21.30を使用します。MVPではNormal / Height参照を出力しません。

保存と寸法変更

Material Zone情報は各Color Textureのvibrant_visuals_material_toolkitプロパティへ保存され、.bbmodel保存とTexture Undo / Redoに含まれます。Zoneマップはraw-u16と連続区間RLEを比較し、小さい方をBase64で保存します。Color画像そのものやZoneごとのマスク画像は保存しません。

Texture寸法が保存時から変わった場合は自動変形しません。表示されるDialogで、最近傍リサイズまたはマスク初期化を選択してください。

書き出し先に同名ファイルがある場合は、対象一覧を確認してから処理します。承認した場合は元ファイルを.bak-YYYYMMDD-HHMMSS形式でバックアップしてから上書きします。

標準Material Previewとの連携

「標準Material Previewへ反映」は、既存または新規Texture Groupへ生成MER / MERSを通常Textureとして追加または更新します。ユーザーが用意した既存MER / MERSがある場合は、確認なしに置き換えません。

Blockbench標準Material PreviewではMERのRGBを確認できますが、Zone OpacityとMERS Subsurfaceは完全には再現されません。正確な各値はPanel内の2Dチャンネル表示と書き出したPNGで確認してください。プラグインは標準Material Preview関数、Three.js Renderer、Shaderを差し替えません。

Phase 1調査メモ

Blockbench 5.1系のBBPlugin、Panel、Dialog、Action、Property、Texture、TextureLayer、TextureGroup、Undo、スコープ付きファイルアクセスを前提に実装しています。標準TextureGroupMaterialConfigが持つMER / MERS、1.16.100 / 1.21.30、Material Preview連携を基準にしています。

Blockbench 5.1.0の型定義に未掲載で、5.1.0〜5.1.6本体に存在するsubsurface_valueへのアクセスだけは標準PBR Adapter内の局所型拡張に限定しています。Bedrock NormalのY反転を含む将来対応でもBlockbench標準実装を基準にします。

参考:

• Blockbench 5.1.6 PBR実装
• Minecraft Texture Set仕様

MVP対象外

次の機能はMVPへ混在させず、後続Phaseへ分離しています。

• Phase 3: Fill、矩形、色範囲、UV Face / Island、プリセット、Normal / Height生成、競合検出、透明度診断、Resource Pack検証
• Phase 4: Vibrant Approx Preview、Bloom、Subsurface 3D近似、Lighting Presets、Tone Mapping、独自Shader / Post Processing

旧pbr_previewプラグインや既存VS Code版MER / MERS生成器の画像処理コードは共有していません。

Blockbench 5.1.6手動確認項目

• Bedrock Entity、Bedrock Block、Generic ModelでZone編集と書き出しを確認
• Body / Light / Glass / Glowing GlassのColor Alpha、MER Green、MERS AlphaをPNGで確認
• 標準Material Preview反映前後とアンロード後を比較
• ブラシ、Zone追加・削除、値変更のUndo / Redoを確認
• 上書き拒否、バックアップ生成、.bbmodel保存後の再読込を確認