キューブの陰影焼き込み

Bedrock Model / Generic Modelのキューブをそのまま使って、隙間・接触部分の陰影（Ambient Occlusion / AO）を通常のテクスチャに焼き込むBlockbenchプラグインです。設定画面・メニュー・エラーメッセージは日本語です。

配布用ファイルは cube_ambient_occlusion.js の1つです。現在のバージョンは 1.1.0。Node.jsや追加ライブラリーの導入は不要です。Blockbench 5.0以降を対象にし、5.2.1で動作確認済みです。

インストール

1. Blockbenchで ファイル → プラグイン を開きます。
2. ファイルから読み込む（Load Plugin from File） を選びます。
3. このフォルダーの cube_ambient_occlusion.js を選択します。

ファイル名は変更せずに読み込んでください。Blockbenchは拡張子を除いたファイル名と、プラグインID cube_ambient_occlusion が一致することを要求します。旧版の cube-ambient-occlusion.js は読み込みに失敗するため、修正版のファイルを使用してください。

Blockbenchの設定言語に関係なく、このプラグインの操作画面は日本語になります。

旧版を導入済みの場合は、プラグイン画面で旧版を削除してから、このファイルを読み込み直してください。以前保存した影の設定・品質は、新しい設定に引き継ぎます。

基本の使い方

1. Bedrock ModelまたはGeneric Modelを開き、キューブにテクスチャを割り当てます。
2. 編集またはペイントモードで、陰影を付けたいキューブを選びます。複数選択できます。
3. ツール → キューブの陰影焼き込み を開きます。
4. 最初は 影の濃さ65%、範囲4、ハイライトの濃さ35%、範囲4、サンプル数64 で試します。設定画面の 初期設定に戻す で、この状態に戻せます。
5. 焼き込む を押します。表示中の全キューブが、光を遮る形状として計算に使われます。
6. 計算が終わると、対象テクスチャに 「陰影付きテクスチャ」 レイヤーが作成されます。
7. テクスチャを通常の PNG として保存して、Bedrockのリソースパックで使用します。

元のキューブ、ボーン、回転、UV、テクスチャの解像度は変更しません。モデルをGeneric Modelに変換したり、キューブをメッシュに変換したりする必要はありません。PNGを利用するゲーム側には、このプラグインは不要です。

設定

項目	内容
焼き込む対象	選択したキューブ、または表示中の全キューブ
影の色	初期値は黒。選んだ色へ向けて暗い部分の色を混ぜます
影の濃さ	0〜100%。0なら影を付けません。初期値65
影の柔らかさ（ガンマ）	0.2〜2。大きいほど弱い影が控えめになります。初期値1
影の範囲	近くの形状を調べる距離。0.01〜256、初期値4
ハイライトの色	初期値は白。周囲に露出した縁に、この色を混ぜます
ハイライトの濃さ	0〜100%。0ならハイライトを付けません。初期値35
ハイライトの柔らかさ（ガンマ）	0.2〜2。大きいほど弱いハイライトが控えめになります。初期値1
ハイライトの範囲	明るくなる縁の幅に影響する距離。0.01〜256、初期値4
サンプル数（1ピクセルあたり）	10〜10000の整数を自由に指定。初期値64。多いほど滑らかになりますが計算に時間がかかります
計算方法	「均等」または「ランダム」。均等は計算方向を規則的に分散し、ランダムは方向を不規則に分散します。比較しやすいよう、ランダムでも同じ設定・モデルなら同じ結果になります
仮想の床	表示中のキューブの最下点に床があるものとして、底の接触陰影も焼き込みます
元のテクスチャの透明度を保持	初期値オン。透明・半透明のアルファ値をそのまま維持します。オフにすると、焼き込む面の透明部分にも影・ハイライトを描き込みます
透明部分から光が抜ける計算をする	初期値オフ。オンにすると、遮る面のテクスチャの透明度を調べ、透けた面の奥にある形状まで計算します。半透明にも対応しますが、計算が重くなります

両方の範囲は モデルの単位 で指定します。通常は1ブロックが16単位です。テクスチャの解像度を変えても、同じモデル上の距離になります。

影とハイライトの濃さを両方0にすれば元の画像のままです。試し焼きにはサンプル数32〜64、細かい仕上げには128以上を使えます。最大値10000では時間がかかるため、まず少ない値で調整してください。

影が見つからないときは、他のキューブが近くにあるか確認して、影の範囲を広げてください。単独の直方体は、仮想の床を使わない場合、通常ほとんど暗くなりませんが、縁にはハイライトが付きます。特定方向からの照明や、地面に落ちる影の画像を生成する機能ではありません。

元のBaked Ambient Occlusionで省略していた種類の設定を追加しましたが、キューブに合わせて独自に計算しています。元プラグインと同じ数値を入れても、仕上がりは完全には一致しません。

やり直し・元に戻す

• Ctrl + Z：焼き込みを1回分戻します。Redoにも対応します。
• ツール → キューブの陰影を取り除く：現在のプロジェクトで生成した陰影レイヤーを取り除き、元のレイヤーの表示を復元します。この操作もUndoできます。
• 再び焼き込む：元のレイヤーから再計算し、前回の陰影レイヤーを置き換えます。繰り返しても影が累積しません。
• 計算中 → 中止：結果を適用せず終了します。

元のレイヤーは非表示で保持します。完成レイヤーは、元画像・影・ハイライトを合成した通常のカラーレイヤーです。透明度は設定に応じて保持、または描き込みます。

元画像の色を直したい場合は、まず 「キューブの陰影を取り除く」 で元のレイヤー表示に戻し、塗り直してから焼き込みます。生成したレイヤーに直接描いた内容は、再実行すると置き換わります。.bbmodel として保存すると、プラグイン導入中は元レイヤーの表示情報も保存・再読込できます。PNGにはレイヤーは保存されません。

対応範囲・制限

• キューブ専用です。Generic Model内の自由形状のMeshは、焼き込み対象にも影を遮る形状にも含めません。
• Box UV、面ごとのUV、反転・回転UV、キューブと親グループの回転に対応します。本体の表示形状・UVを参照します。
• 非表示または書き出し対象外のキューブ／グループは計算から除きます。
• UVを共有する面には同じ陰影が付きます。 選択した面と未選択の面が同じ画像位置を使っている場合、両方に反映されます。対象面同士のUVが重なるピクセルは、陰影を平均します。面ごとに違う影が必要な場合は、先にUVの重なりを解消してください。
• 「元のテクスチャの透明度を保持」がオンなら、完全透明のピクセルは変更せず、半透明を含めて元のアルファ値を保ちます。オフなら、対象面に含まれる透明ピクセルの不透明度が増えることがあります。どちらの場合も、対象面のUV外のピクセルは変更しません。
• 「透明部分から光が抜ける計算をする」がオフなら、遮る面を不透明として計算します。オンなら完全透明の面を通り抜け、半透明の面では遮る量を減らします。テクスチャがない面は不透明として扱います。
• アニメーション付きテクスチャには対応していません。アニメーション・ポーズ・ディスプレイモードでは、編集またはペイントモードに戻してから実行してください。
• 影はテクスチャに固定されます。ゲーム内で動かしても、陰影は自動で変化しません。
• 対象画像の合計は419万画素以下、表示中のキューブは2万個以下です。透明部分の計算がオンの場合は、遮るキューブが使う画像も画素数に含めます。大きいモデルでは少ないサンプル数から試してください。
• 計算中にプロジェクト、形状、対象の選択、テクスチャが変わった場合は、結果を適用せず中止します。

開発時の検証

Blockbench 5.2.1のWebビルドを使った結合検証で、配布ファイル名を使う「ファイルから読み込む」処理、Bedrock Model / Generic Modelのキューブへの焼き込み、14項目の日本語設定画面、旧設定の引き継ぎ、初期設定への復元、回転した親グループとキューブ、反転UV、形状の維持、透明度の維持、Undo / Redo、再実行による置換、サンプル数10000での中止、.bbmodel の保存・再読込後の元レイヤー復元を確認しました。数値テスト16項目も通過しています。数値テストでは、ハイライト、両方のガンマ・色・濃さ、透明な遮蔽物とその奥の形状、半透明、透明度保持の切り替え、任意サンプル数、ランダム計算の再現性も確認しています。

数値テストはNode.jsだけで実行できます。

cd cube-ambient-occlusion
npm test

独立したブラウザーでのBlockbench結合テストは tests/integration.cjs です。ユーザーのBlockbenchプロファイルを操作せず、インストール済みアーカイブを読み取るローカルテストサーバーと、一時ブラウザーを使用します。外部へのページ通信はテスト側で遮断します。

必要な環境変数：

• CAO_PLAYWRIGHT：Playwrightモジュールのパス。未指定時は通常の playwright を使用。
• CAO_BROWSER：Chromium系ブラウザーの実行ファイル。未指定時はPlaywright標準のChromiumを使用。
• BLOCKBENCH_ASAR：本体の resources/app.asar。未指定時はWindowsのユーザー別インストール先。
• BLOCKBENCH_WEB_BUNDLE：同じバージョンのBlockbench Webビルド。未指定時は、この作業フォルダーにある player-motion-studio/_dev/web-bundle.js。

npm run test:integration

本体のコードやWebビルド、検証用のブラウザーはプラグインに同梱しません。検証のスクリーンショットは _dev/ に保存します。