Bedrock Model Merger

複数の Minecraft Bedrock Entity 用 .bbmodel を、形状・Bone 階層・Transform・Texture・UV を保持したまま、新しい 1 つの Blockbench Project と 1 枚の Texture Atlasへ統合する Desktop 版向けプラグインです。

インストール

1. Blockbench Desktop 5.0.0 以降を起動する
2. File > Plugins... を開く
3. タイトルバーの Load Plugin from File を選ぶ
4. bedrock_model_merger.js を選ぶ

開発中は JavaScript ファイルを Blockbench のウィンドウへドラッグ＆ドロップしても読み込めます。

使用方法

1. Tools > Bedrockモデルを統合 を開く
2. Add Models... で複数の .bbmodel を選ぶ
3. Bone Conflict Handling と Texture Atlas の設定を選ぶ
4. geometry.merged_model のような Geometry Identifier を入力する
5. Merge Models を押す

既存Projectだけを整理する場合は Tools > UVとTextureを最適化 を開き、モデル全体 または 選択中のCube を選びます。Previewを確認してから確定すると、TextureとUVを1回のUndoで戻せる同一Transactionとして更新します。

入力ファイルと現在の Project は変更されません。検証・Texture 読み込み・Atlas 生成・Transform 比較がすべて成功した後に、新しい Bedrock Entity Projectを作成します。新規 Project の構築中に失敗した場合は、不完全な Project を閉じて元の Projectへ戻します。

Bone Conflict Handling

Create model parent bones

既定値です。共通の root の下へモデルごとの identity Bone を作り、各モデルの Bone 名にはモデル名の接頭辞を付けます。追加する親 Bone の Pivot と Rotation はゼロなので、子の World Transform は変化しません。

Rename duplicate bones

最初の Bone 名を維持し、以降の同名 Bone を body_2、body_3 のように変更します。階層は UUID ベースで再構築します。

Merge same-name bones

同じ親の下にあり、Pivot、Rotation、Mirror、Visibility、Reset、Bedrock Binding が一致する同名 Bone だけを統合します。

Transform、Bedrock プロパティ、または親が異なる場合は Rename、Skip、Cancel を選択します。安全性のため、競合を自動的に統合しません。

Texture-aware UV Auto Repack

既定で UV配置を最適化 と UVと一緒にTexture Pixelを移動 が有効です。処理前Textureを不変のSource CanvasへSnapshotし、新規Destination Canvasへ各Islandを1回ずつコピーした後でUVを更新します。Destinationから別領域へコピーしないため、移動順による上書きは起きません。

• Box UVはCube全体の展開矩形を1 Islandとして扱う
• Per-face UVは各FaceをIslandとして扱う
• 完全一致UVは1つのShared Islandとして維持する
• 部分重複は分離せずComposite Islandへ統合して警告する
• 透明Pixelを含むUV矩形全体をコピーする
• MaxRectsでPadding込みの矩形を配置する
• imageSmoothingEnabled = falseで1 pixelを1 pixelのままコピーする
• 使用Island面積をAtlas面積で割り、Paddingを除いたUV UtilizationをPreviewへ表示する
• Commit前に各FaceのRGBA byte列が処理前後で一致することを検証する
• 未使用の非透明Pixelは既定で保護し、無効時はPreserve / Discard / Cancelを確認する
• Layer付きStandalone TextureはLayer数、名前、表示、Opacity、Blend Modeを維持し、全Layerへ同じ配置を適用する
• Layer付きMerge入力は元Projectを変更せず、明示確認後にFlattenした複製からAtlasを作る

Safeが既定Modeです。回転・拡縮を行わず、Shared UV、未使用Pixel、1px Paddingを保護します。CompactとMaximum Compactは将来拡張用です。90度回転はUI予約項目として表示しますが、現行の安全実装では有効化を拒否します。Box UV、Mirror、Face Rotationを完全に保つ回転変換が検証されるまで黙って適用しません。

Texture Atlas

• UV最適化時はMaxRects、無効時は従来のShelf Packingで矩形を配置
• Texture は90度回転しない
• 元画像を拡大縮小しない
• Canvas の smoothing を無効化
• 背景と Padding は完全透明
• Padding は 0、1、2、4 pixelで既定値は1
• Power-of-two 有効時は縦横をそれぞれ必要最小限の2の累乗へ切り上げ
• 希望するTextureサイズで32から4096を指定可能
• 指定サイズに収まらない場合は失敗せず、次の正方形2の累乗サイズへ自動拡張
• 4096px を超える場合は続行確認
• 16384px または推定 RGBA メモリ 512 MiB を超える場合は中止

Merge textures を無効にできるのは、使用中の元Textureが1枚だけの場合です。Bedrock Entity Project は単一Textureを前提とするため、複数Textureを安全に保持できない設定は拒否します。

対応UV

Box UV

Cube の uv_offset へ Atlas 内のTexture本体位置を加算します。Cube寸法から決まるFace展開は変更しません。mirror_uv は元の値を維持します。

Per-face UV

north、east、south、west、up、down の uv 矩形の開始点と終点へ同じ Atlas offsetを加算します。これにより負の uv_size、Face Rotation、Mirror 表現を維持します。

UV Safety Mode

Project UV Sizeと実Texture Pixel Sizeが異なる高解像度Textureに対応しています。例えばUVが64x64、Textureが128x128の場合は、UV 1単位 = Texture 2pxとしてPixel密度を保持します。

• 縦横が同じ整数倍率であること
• BedrockではProjectのresolution.width / resolution.heightをUV座標系として使用すること
• Texture内の古いuv_width / uv_heightがProjectと異なる場合は警告し、Project側を優先すること

1倍と2倍などPixel倍率が異なるTextureも、各Islandを実Pixel座標へ正規化して統合します。Box UVはCube全体を1 Islandのまま維持し、同じ展開矩形内のPer-face UVへ変換してPixel密度を保持します。縦横で倍率が異なる異方性Textureのみ安全に拒否します。

Animation

Animation と Animation Controller は検出して警告します。バージョン 1.1.0 では統合しません。ユーザーが続行を明示した場合のみ、Geometry とTextureを統合します。

内部では元Bone UUIDから統合後Bone名・UUIDへの対応を保持しているため、将来のAnimation対応で参照を書き換えられる構成です。

非対応機能

• Generic Model、Java Block Model、Bedrock Block、Bedrock Legacy Model
• Mesh、Locator、Null Object、Texture MeshなどCube以外のOutliner Element
• AnimationとAnimation Controllerの統合
• 縦横でPixel倍率が異なるTexture
• Textureの拡大縮小や90度回転を伴うAtlas配置
• 壊れたOutliner、重複UUID、未参照ノードを推測で修復する処理

注意事項

• 統合後は新規Projectで形状とUVを確認してから保存する
• 元モデルのAnimationは統合Projectへ含まれない
• Textureの相対パスは .bbmodel の保存場所を基準に解決する
• 詳細調査が必要な場合は Detailed debug log を有効にしてDeveloper Consoleを確認する
• Merge AtlasのUndoは Codecs.project.merge が作成する新規Project内の Merge project 履歴で扱う
• 単独最適化はTexture bitmap、UV、UV SizeをOptimize UV & Textureの1履歴で扱う

Known Issues

• NodeテストはRGBA Canvas互換実装でPixel一致を検証しているが、GPU表示を含む最終確認はBlockbench Desktop上で必要
• TGAなどBlockbench側のデコーダーを使うTextureは、デコーダーが返すCanvas内容に依存する
• Bone名をAnimationや外部Controllerから文字列参照している場合、Animation非対応のため参照は移行されない
• 複数Textureが登録されていても未使用TextureはAtlasへ含めない
• 新規統合ProjectにBlockbenchが初期Textureを作成した場合は、最終Atlas確定前に初期Textureを除去してAtlas 1枚だけを残す
• 未使用Pixel保護は使用中UV領域を除外した非重複矩形だけを移動し、元Texture全体を下側へ二重コピーしない