scenario-godot-rendering-lighting

Godot のレンダリングとライティング（ライター／グラフィックス・テクニカルアーティスト向け）

対象：Godot 4.7.2.stable、macOS Apple Silicon（デフォルトは Metal）。

ここでいうエキスパートレベルとは、測定に基づくループでライティングを調整することです。キャリブレーション用シーンを用意し、一度に変更する変数はひとつだけにして、変更のたびにレンダリング画像を確認し、画像上に数値を記録し、各エフェクトの GPU コストを把握します。レンダラーと GI 方式は、ほかの設定で可能なことを左右するため、最初に選びます。アートディレクション（明度パターン、暖色と寒色、焦点のコントラスト）は、インスペクターではなく、エージェントが実際に開いたピクセルを見て評価します。ここで名前が挙がっている関連スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください （npx skills add scenario-labs/skills --skill <name>）。無人で処理を進める場合は、ツールのスキーマをもとに作業し、不足しているスキルを明記してください。

必須の背景知識： scenario-godot-expert（チャンネル、gd_run、レビューループ、4.7 の注意点）。

方針（専門家から得た知見）

1. 静的なシーンにはライトマップを使います。 SeasonalAsh は RTX 4060 で計測し、SDFGI では fps が約半分になり、VoxelGI では 60〜80 fps、ライトマップが最速だったと報告しています。ワールドを破壊できない場合は、ライトマップが「10 回中 9 回」は最適です（SeasonalAsh 13:07、17:48）。4.7.2 では、エージェントがライトマップをベイクできます。エディターのジョブが「Bake Lightmaps」を自動で押します（P7）。動的なジオメトリや移動する太陽がある場合は SDFGI または VoxelGI、静的な場合は LightmapGI と ReflectionProbes を使います。
2. レベルにライティングを施す前に、ルックデブ用シーンで調整します。 Brackeys はガイド用の球（暗色、白色、鏡面）と Display > Lighting を使います（Brackeys 7:19、28:53）。Picster は後で再テストできるよう、プリミティブのブロックアウトを残しています（Picster 2:05、1:15:35）。 lookdev.gd は屋外と密閉された部屋を構築します。
3. 見た目でトーンマッパーを選び、その後に露出を再調整します。 Brackeys と Wild Ox は AgX、SeasonalAsh と LegionGames は ACES を使っています。計測では、AgX は p95 が最も低く、クリッピングがなく、Filmic や ACES では黄色に寄ってしまうオレンジ色の発光体を、オレンジ色のまま保ちます（P5）。AgX は最も負荷の高いトーンマッパーでもあり、スマートフォンでは考慮が必要です（docs）。新しい Environment の初期値は Linear です（P1）。必ず設定してください。
4. 発光を二段階で分かりやすく表現します。 Glow は発光体を明るく見せ、実際のライト（またはベイク済み GI）はシーンを照らします（Brackeys 13:56、Gamefromscratch 7:09）。Glow の初期値は 4.6 で変更されました（Screen、強度 0.3、レベル 2〜4 は 0.8／0.4／0.1、P15）。4.6 より前に作成したシーンは再調整してください。
5. SDFGI と VoxelGI を併用せず、最初のフレームで SDFGI を信用しないでください。 SDFGI の収束には約 30 フレームかかり（P1）、有効化直後は暗くなります（P8）。GDQuest は有効化した後にトーンマップを再調整しています。
6. ボリュームフォグの品質は Project Settings で設定し、負荷もそこに左右されます。 Four Games は、ボリュームサイズ 64 は低すぎ、256 が良い妥協点だとしています。ゴッドレイには異方性を約 0.7 にし、長さを短くする必要があります（Four Games 0:32〜3:52）。主役となるライトの Volumetric Fog Energy を上げ、懐中電灯の値は 0.1 に下げます（Brackeys 19:52、LegionGames 2:08）。計測では、1080p で 512 にすると +3.9 ms の負荷がかかります（P9）。
7. 基本の見た目はすべてのレンダラーで成立させ、各ティアでは要素を追加するだけにします。 Mobile は SDFGI、VoxelGI、SSR、SSAO、SSIL、ボリュームフォグを無視し、Compatibility は SSAO 以外を同様に無視します。読み込み時にはそれぞれ 1 行の WARNING が出力されます（P4）。フォグ、Glow、トーンマッパー、ライトマップ、プローブを使えば、どこでも見た目を維持できます［追加］。4.4 以降、レンダラーが Compatibility にフォールバックしても何も通知されず、fallback_to_opengl3 の初期値は true です（docs、P15）。PC では false に設定してドライバーの不具合を明確に検出してください。Android では true のままにする選択肢もありますが、Compatibility での見た目をテストしてください。
8. CompositorEffect は GLSL compute であり、.gdshader ではありません（Acerola 9:39）。docs では Forward+ と Mobile が対象として挙げられていますが、docs の手法（color をストレージイメージとして扱う方法）は、4.7.2 の Mobile では color バッファーにストレージビットがないため 172 件のエラーを出力し、Compatibility ではエフェクトが何も通知せず無視されます（P12）。Forward+ で使用し、Mobile ではガードしてください。コールバックはレンダースレッドで実行されます。メインスレッドと共有する状態にはミューテックスを使い、プッシュ定数は 16 バイトの倍数にパディングし、アップスケーリングはポスト処理の後に実行されることを覚えておいてください（docs）。UI を重ねるポスト処理には、どこでも使える CanvasLayer ColorRect が適しています（Lukky）。

最初に決めること

入力項目	指定がない場合のデフォルト
対象プラットフォームと各プラットフォームのレンダラー	Forward+ デスクトップ。プロジェクトのデフォルトは rendering_method.mobile="mobile"、.web="gl_compatibility"
フレーム予算と基準 GPU	PC で 60 fps（16.6 ms）。Vulkan で測定します（Metal では GPU ms が 0 と報告されます）
静的または動的なワールド：動く太陽、破壊可能なジオメトリ、サイズ	静的な屋内：ライトマップ。昼夜が変化する屋外：SDFGI。中規模の動的な環境：VoxelGI
雰囲気の参考資料と時刻	画像 1 枚、または 3 つの単語（「冷たい夜明け、霧がかっている、希望に満ちた」）
主役の被写体とカメラ	Camera3D のパス。なければシーンの現在のカメラ
アセットの入手元	blender-expert または scenario-* スキルの glTF：UV2 と予期しない発光を確認します

ワークフロー

ツールキットを読み込みます。sys.path に skills/scenario-godot-expert/scripts と skills/scenario-godot-rendering-lighting/scripts を追加し、import gd_lighting as gl を実行してから gl.install(P) を呼び出します。全コードは references/procedures.md を参照してください。

1. レンダラー。 project.godot（rendering_method、Jolt、フォールバック）を確認します（P1）。 gl.capture_renderers(P, scene) はレンダラーごとに1つのビューをキャプチャし、WARNING 行を返します。 ゲート：レンダラーが project.godot に記述されていること、パリティシートが開かれていること、引き継ぎに無効化した機能が記載されていること。
2. ルックデブ。 gl.build_lookdev(P)（P3）を実行し、3台のカメラでキャプチャします。ゲート：look_checks の p95 と p05 の差が 0.25 を超え、クリップが5パーセント未満であること。暗い球体で形状が見え、白がクリップせず、鏡に空が映っていることを確認します。
3. GI とベイク。
   • 静的：gi_bake.gd:prepare（太陽は Dynamic、その他は Static、非表示ライトは Disabled、UV2 を確認）を実行し、続いてウィンドウ表示の gi_bake.gd:lightmap エディタージョブを実行します（P7）。
   • 中規模の動的シーン：ウィンドウ表示で gi_bake.gd:voxelgi を実行します（P6）。
   • オープンワールド：オクルージョンを有効にした SDFGI を使用し、バウンスのフィードバックは 0.5 以下、Y スケールは 75 または 50 パーセント、最大距離はカメラのファーより小さく設定し、40フレーム以上経過後にキャプチャします（P8）。
   • ライトマップとともに ReflectionProbes を追加します（追加しないとスペキュラーが得られません）。ゲート：監査で GI エラーがないこと、ベイクファイルが存在すること、室内のキャプチャを開き、光漏れ、継ぎ目、暗い斑点を確認していること。
4. キーライト、フィルライト、実用光源。 ライトは光源の位置に置き、色を合わせます。影はキーライトのみで有効にし、ろうそくは影なしで照射距離を短くし、人工光源は太陽より弱くします（Brackeys、SeasonalAsh）。 gl.audit(P, scene, ["forward_plus", "mobile"]) を実行します（P2）。ゲート：エラーフラグがないこと、squint(img) を1つの焦点値で開いていること、focal_contrast が少なくとも 0.05 であること。
5. 環境とポスト処理。 gl.sweep で一度に1つの変数を調整します。トーンマッパー（tonemap_variants、P5）、露出、グロー、フォグ、ボリューメトリックフォグ（P10）の順に調整し、最後に Adjustments を設定します（カラコレクショングラデーションで影を寒色に、ライトを暖色にします。Picster 45:07）。ゲート：各シートを開き、数値とともに最良の設定を明記し、指示がない限り、どのバリエーションもクリップが5パーセントを超えないこと。
6. 影。 まず shadow_normal_bias、次に shadow_bias をスイープします（SeasonalAsh の 0.05 とデフォルトの 0.1、フレーム 4:13）。ブレンド分割を有効にし、最大距離をプレイ可能な範囲に設定します（屋外の Picster は400、デフォルトは100）。ゲート：かすめる角度のクローズアップを開き、縞がなく、接触影が接地していることを確認します。
7. ティアとコスト。 graphics_tiers.gd のプリセットを、--rendering-driver vulkan で call と measure=60 を使用してスイープします（P11）。低と中では影の分割数を2、高とウルトラでは4にします。P9 テンプレートを基準にエフェクトごとの差分を確認します。Mobile では、Apple なら空間 MetalFX、それ以外ではバイリニアを使用します（P13）。ゲート：各ティアの GPU ms がターゲットレンダラーの予算内に収まり、低ティアでも雰囲気が保たれていること。
8. カスタムポスト処理（任意）。 compositor_tools.gd:attach と post_effect.gd、および GLSL コンピュートシェーダーを使用します（P12）。ゲート：Forward+ ではエフェクトが表示され、Mobile では警告が1つだけ出てスキップされること。

エキスパート向けチェックリスト（計画に記載してください）

• ベイク範囲。 非表示のライトもベイクされます。Bake Mode を Disabled に設定してください（ドキュメント）。メッシュの GI モードはデフォルトで Static なので（P15）、プレイ可能でないジオメトリは GI モードを Disabled にして、ベイクを高速化し、品質を向上させてください（SeasonalAsh 13:39）。
• インポートとリポジトリ。 glTF の meshes/light_baking=2（Static Lightmaps。デフォルトの 1 は通常の Static）と meshes/lightmap_texel_size（デフォルトは 0.2。ベイクがクラッシュする巨大なシーンでは 0.5 以上）を使用します（P15、ドキュメント）。*.unwrap_cache を gitignore に追加しないでください（UV2 の安定性を保ちます）。.lmbake は外部に置いてください（ドキュメント）。
• 光漏れ。 壁は閉じた厚い構造にします［追記］。密閉された部屋では、LightmapGI Interior と環境モード Disabled を使用してください（ドキュメント）。
• デノイザー。 rendering/lightmapping/denoising/denoiser はプロジェクト全体に適用されます。0 は JNLM（デフォルト）、1 は OIDN（外部バイナリが必要）です（ドキュメント、P15）。
• シャドウマスク。 LightmapGI.shadowmask_mode：None（0、デフォルト）、Replace（1。近距離ではリアルタイム、最大距離以遠ではベイク。植生に最適）、Overlay（2。カメラの処理が高速）。対象は最初の Dynamic DirectionalLight3D のみです。ベイクし直さずに切り替えられます（ドキュメント、P15）。
• 暗い屋内のベイク。 ライトマップは環境光を無視します。まず補助ライトまたはバウンスライトを追加してください。Spannule の最後の手段は、EXR を乗算して環境光を約 8 パーセント追加することです（1JvPYUl1nfo 4:00）。
• SSAO は環境光を暗くするだけです。ssao_light_affect のデフォルトは 0.0 です（ドキュメント、P15）。
• シャドウ。 Cull Mask ではシャドウの投影を止められません。メッシュの Cast Shadow をオフにしてください。デフォルトのアトラスには、シャドウを投影する位置ライトを 88 個収容できます（クアドラント 4+4+16+64、P15）。すべての PSSM 分割に含まれるメッシュは 5 回描画されます。Forward+ では、表示されている AreaLight3D が 1 つあるだけで、すべてのオブジェクトの負荷が増加します。Compatibility ではシャドウ付きライトが sRGB でレンダリングされるため、エネルギーを再調整してください（ドキュメント）。
• ポストプロセス。 3D LUT は Texture3D（importer="3d_texture"、slices/horizontal）としてインポートする必要があります。16 個のスライスを含む 256x16 のストリップは、16x16x16 として読み込まれます（P15）。HDR Clamp Exposure は約 4096 を超える輝度のみを圧縮します（太陽のピクセル値 100000 は 14988 になり、50 は 50 のままでした。P15）。デバンディングはデフォルトでオフです。露出と DOF は Camera3D の CameraAttributes にあり、品質設定はプロジェクト設定にあります。

数値

値	比較対象	出典
shadow_bias 0.05	デフォルトは 0.1	SeasonalAsh frames 4:13; P1
シャドウのぼかし 2～3	デフォルトは 1.0	SeasonalAsh 5:13
方向光の最大距離 100	デフォルト。Picster は屋外で 400	P1; Picster 54:08
ボリューメトリックフォグのボリュームサイズ	デフォルト 64、推奨 256、最適 512。1080p でそれぞれ +0.2～1.1（64）、+1.5～2.7（256）、+3.9（512）ms	Four Games 2:44; P9
ゴッドレイ用フォグの異方性 0.7	デフォルトは 0.2	Four Games 0:32; P1
SDFGI の収束	約 30 フレーム（列挙値のインデックス 5）。40 フレーム後にキャプチャ	P1, P8
SDFGI のバウンスフィードバック	デフォルトは 0.5。0.5 を超えると暴走するおそれがあります	P1; Omogonix 28:10
SDFGI の最大距離	デフォルトは 204.8、カメラの遠クリップ距離は 4000	P15
メッシュあたりのライト数	Mobile はオムニライト 8 個 + スポットライト 8 個。Forward+ はビューあたり 512 個のクラスタ要素	docs
スポットライトのシャドウ角度	89° を超えると失敗します	docs
LightmapGI の品質設定順	スーパーサンプリング、テクセルサイズ、品質の順	Brackeys 34:34
LightmapGI の Low ベイク、ルックデブ用ルーム	ベイク時間 3.6～15 秒（負荷時の M5 Max）	P7
1080p のエフェクト GPU 時間（小規模シーン）	SSIL +1.4～1.7、SSR +0.9～1.3、SDFGI +0.7～1.1。SSAO、グロー、TAA、SMAA、MSAA 2x はそれぞれ 0.8 未満（0.5 未満は誤差範囲）	P9, Vulkan
ティアごとの GPU 時間（Forward+ / Mobile）	低 1.5 / 0.62、高 2.9～4.3 / 1.73、ウルトラ 3.6～4.85 / 1.64	P11, tiny scene

エフェクトのコストは解像度とシーンによって変わります。数値を引用する前に、P9 のテンプレートを使って再計測してください。

品質ゲート

• 測定可能な項目：対象レンダラーごとに gl.audit のエラーフラグがゼロであること。gd_run.check_all の解析エラーがゼロであること。look_checks でクリップ値が 0.05 未満、黒つぶれ値が 0.3 未満、p95 から p05 を引いた値が 0.25 を超え、focal_contrast が 0.05 以上であること。ベイクファイルが存在し、lightmap_textures が 1 以上であること。.gitignore に unwrap_cache がないこと。各ティアの GPU 時間が Vulkan で予算内であること。
• 視覚的な項目：各コンタクトシートと斜視画像を開いて確認します。焦点となる領域が 1 つ、シルエットが読み取りやすいこと。暖色と寒色の意図が明確であること。光漏れ、継ぎ目、アクネ、バンディングがないこと。発光体が輝いていること。フォグで画面全体が白くならないこと。モバイルと低ティアでも雰囲気が保たれていること。references/critique.md が評価基準です。

よくある間違い

間違い	症状	修正
Linear トーンマッピングのままにする	ハイライトが白飛びし、空が平坦になる	AgX または ACES を使い、その後に露出を調整する
エディターのプレビュー用の太陽光でライティングする	ゲームが灰色になる	シーン内で WorldEnvironment と太陽光を設定する（SeasonalAsh 1:40）
SDFGI と VoxelGI を併用する	バウンスが二重になり、コストがかかる	エリアごとに GI を 1 つだけ使う
UV2 のないメッシュをライトマップする	ベイク結果が黒くなる、または乱れる	プリミティブでは add_uv2 を使い、glTF では Static Lightmaps を設定する
非表示のライトもベイクされる	ゴーストライトが発生する	Bake Mode Disabled にする（prepare が設定します）
Mobile で FSR1 を期待する	バイリニアと同じ結果になり、警告「FSR1 3D scaling is only available when using the Forward+ renderer」が表示される	Apple では MetalFX spatial を使い、それ以外ではバイリニアを使う（P13）
Mobile で docs CompositorEffect を使う	実行ごとに 170 件以上のエラーが発生する	storage-bit ガード（post_effect.gd）
インポートした glTF に不要な emission が残る	小道具が光って見える	emissive_without_glow を監査し、ゼロにする（Gamefromscratch 5:25）
frames_to_converge に「30」を書き込む	enum のインデックスが間違っている	gl.setting_index(key, 30) は 5 を返します
SSAO を有効にしても何も変わらない	直接光では AO が見えない	ssao_light_affect を上げる
LUT を通常の PNG として使う	色補正が無視される	スライスを使って Texture3D として再インポートする

引き継ぎ

• 受け取るもの: scenario-godot-3d-world（レベル、静的／動的の分割、カメラ）； blender-expert および scenario-* スキル（UV2 を含む glTF）；scenario-godot-shaders（マテリアル）； scenario-godot-vfx（エミッシブエフェクト）。
• 引き渡すもの: scenario-godot-performance-export（ティア表、ティアおよびレンダラーごとの GPU ms、設定差分）；scenario-godot-ui（graphics_tiers.gd に対応付けたグラフィックス設定）； scenario-godot-shaders（コンポジター GLSL の要件）；scenario-godot-expert（シート、監査 JSON、整合性に関するメモ）。シーンと .tres ファイルをコミットし、.agent_out/ のシートと JSON も追加します。

Godot 4.7 に関するメモ

4.7.2 で確認済み（references/expert-notes.md、確認済み）：

• LightmapGI.bake はスクリプトでは利用できません。エディターのボタンから実行する方法は機能します（P7）。VoxelGI.bake は存在しますが、ヘッドレス実行では空のデータが保存されます。
• GeometryInstance3D.lightmap_scale は廃止されています。gi_lightmap_texel_scale を使用してください。
• 新しい環境設定：トーンマッパーは Linear、グローは Screen を 0.3、SDFGI のバウンスフィードバックは 0.5 です。
• FSR1 は Forward+ 専用です。MetalFX の空間アップスケーリングは、Metal を使用する Mobile で動作します。
• Metal では GPU の処理時間が 0 と表示されます。--rendering-driver vulkan でプロファイリングしてください。
• AgX は 4.4 で追加されました。Wild Ox は、4.6 で SDFGI と VoxelGI のリーク、グロー、SSR が修正されたと報告しています。そのため、囲い込みボックスなどの 2023 年の回避策を再テストしてください（Wild Ox 2:23）。

参考資料

• references/procedures.md：P0 から P15 までの各手順に、コード全文、ライブテスト、結果の行を記載しています。
• references/expert-notes.md：タイムスタンプ付きの専門家による判断と、確認済みの 4.7.2 の情報を記載しています。
• references/critique.md：画像の評価基準。 references/gui-paths.md：エディター内のパス。 references/sources.md：情報源とタイムスタンプ。
• scripts/gd_lighting.py および scripts/agentkit/rendering/：lookdev、light_audit、sweep、 gi_bake、graphics_tiers、compositor_tools、compositor/。