godot-3d-lighting

3D ライティング

シャドウとグローバルイルミネーションを使ったリアルな 3D ライティングの専門的なガイダンスです。

絶対にしてはいけないこと

• 適切な範囲を設定せずに VoxelGI を使わないでください — 範囲が設定されていない VoxelGI はパフォーマンスを著しく低下させます。必ず size をシーンにぴったり合うように設定してください。
• すべてのライトでシャドウを有効にしないでください — シャドウを生成するライトはそれぞれ負荷が高くなります。シャドウは控えめに使い、DirectionalLight は 1～2 個、OmniLight は最大で約 3～5 個にしてください。
• directional_shadow_mode の設定を忘れないでください — デフォルトは ORTHOGONAL です。広大な屋外シーンでは、遠距離でのシャドウ品質を高めるため、PARALLEL_4_SPLITS を使ってください。
• 完全に動的なシーンで LightmapGI を使わないでください — ライトマップはベイクされます。ジオメトリを動かしてもライティングは更新されません。代わりに VoxelGI または SDFGI を使ってください。
• omni_range を大きくしすぎないでください — 光の減衰は二次関数的です。範囲を 500 にすると、785,000 平方単位に影響します。見た目に問題のない範囲で、できるだけ小さくしてください。
• Lightmap のベイク対象からライトを除外するために、Visible プロパティで Light ノードを非表示にしないでください — ライトを非表示にしてもベイカーには影響しません。ライトの Bake Mode を Disabled に変更する必要があります。
• 紙のように薄い壁で VoxelGI を使わないでください — VoxelGI は 3D グリッドを使ってライティングを評価します。薄い壁（ボクセル 1 個分より薄い壁）では、深刻な光漏れが発生します。ジオメトリを隙間なく閉じるか、外側を隠れた厚みのある MeshInstance3D ブロックで囲んでください。
• カスケードでシャドウバイアスをデフォルトのままにしないでください — デフォルトのバイアスでは、スプリットの境界でピーター・パンニングや光漏れが発生することがよくあります。シーンのスケールに応じて、ライトごとにバイアスを調整してください。
• デノイザーなしで LightmapGI をベイクしないでください — Godot のベイク済みライトマップは、デフォルトではノイズが多くなります。プロ品質の結果を得るには、Project Settings で OIDN または JNLM を使ってください。
• Mobile/Compatibility レンダラーでリアルタイムの SDFGI を使わないでください — SDFGI は Forward+ 専用の機能です。ローエンドのプラットフォームでは、フェイクの GI バウンスライトを使ってください。
• パフォーマンスのために ReflectionProbe で「Update Continuity」を使わないでください — ReflectionProbe は「Update Once」に設定し、必要な場合にのみ手動で更新してください。
• クラスタ化シャドウアトラスをオーバーフローさせないでください — 理由：Forward+ は Omni/Spot のシャドウを共有アトラスに格納します。シャドウ付きの位置指定ライトが多すぎると、アトラスの頻繁な更新、ちらつき、または気付かれないままの品質低下につながります。シャドウ付きの Omni（約 3～5 個）と Spot（約 2～4 個）の数を制限し、アトラスのサイズを大きくする前に light_lod_optimizer.gd / 距離フェードを使ってください。
• 同じクラスタセル内で、シャドウ付きの Omni/Spot を何十個も重ねないでください — 理由：クラスタ化されたライトの反復処理コストは、タイル内で重なるライトの数に応じて増加します。シャドウなしのフィルライトを優先し、omni_range / spot_range を小さくし、distance_fade_* を使って遠くのライトをクラスタから除外してください。

---

利用可能なスクリプト

必須：該当するパターンを実装する前に、適切なスクリプトを読んでください。

ゴールデンパス（1 つ選択 — 併用するスクリプトは読み込まないでください）

シーン	読み込む	読み込まない
屋外 Forward+	shadow_cascade_tuner.gd + sdfgi_probe_manager.gd（時刻による変化がある場合は day_night_cycle.gd も）	fake_gi_bounce.gd、ハイブリッド構成以外での屋内 VoxelGI ベイク、雰囲気の調整が目的でない場合は environment_blender.gd / フォグ
屋内 密閉されたジオメトリ	必須 VoxelGI（light_probe_manager.gd + lighting_manager.gd + ReflectionProbes を使用）	狭い屋内での SDFGI、Mobile を対象とする場合以外の Mobile 用フェイク GI、ゾーンブレンド以外での空／フォグ用スクリプト
モバイル / Compatibility	必須 fake_gi_bounce.gd + light_lod_optimizer.gd のライト予算設定	リアルタイム SDFGI（Forward+ のみ）、HDR の空／ボリュームフォグ設定
ライトマップベイク / ハイブリッド静的構成	必須 lightmap_bake_helper.gd（屋外では Shadowmasking も）	ベイクの代替としてのランタイム SDFGI、Visible によるライトの無効化
空 / 環境のブレンドのみ	environment_blender.gd	トーンマップ／アンビエント／空のみを変更する場合のカスケード／GI マネージャー
ボリュームフォグ / 光芒	volumetric_fx.gd（局所的な密度には volumetric_fog_zones.gd も）	ライト予算／シャドウアトラスの調整のみを行うタスク
ライト予算 / シャドウ LOD のみ	light_lod_optimizer.gd、shadow_bias_tuner.gd	要件に含まれない限り、environment_blender.gd、volumetric_fx.gd、昼夜サイクルは読み込まないでください

day_night_cycle.gd

時刻に応じて太陽の位置と色を動的に変更します。DirectionalLight3D の回転、色温度、強度カーブを処理します。屋外の昼夜システムに使用します。

light_probe_manager.gd

グローバルイルミネーション設定のための VoxelGI および SDFGI の管理です。

lighting_manager.gd

動的なライトのプーリングと LOD を行います。カメラからの距離に基づいてライトのカリングとシャドウの切り替えを管理します。ライトが多数ある場合のパフォーマンス最適化に使用します。

volumetric_fx.gd

ボリュームフォグとゴッドレイの設定です。ランタイムでのフォグ密度／色の調整と光芒の設定を行います。雰囲気のある表現に使用します。

shadow_cascade_tuner.gd

太陽の角度とカメラの傾きに基づいて、DirectionalLight3D のシャドウ分割距離を動的に調整する高度なロジックです。

lightmap_bake_helper.gd

ハイブリッドな静的／動的シャドウに Shadowmasking モードを使用する、高度な LightmapGI 設定パターンです。

sdfgi_probe_manager.gd

リアルタイムのグローバルイルミネーション（SDFGI）用の動的な品質スケーラーです。パフォーマンスと品質のバランスを取るため、セルサイズとオクルージョンを調整します。

volumetric_fog_zones.gd

Tweens と Area3D トリガーを使用し、洞窟の入り口や森の空き地などで局所的なフォグ密度を滑らかに遷移させます。

fake_gi_bounce.gd

効率的な「Mobile-GI」パターンです。シャドウを無効にしたディレクショナルフィルライトを使い、床からの光の反射をシミュレートします。

environment_blender.gd

ゲームプレイ中に WorldEnvironment のパラメーター（Sky、Ambient、Tonemap）を遷移させるための設計パターンです。

shadow_bias_tuner.gd

高精細なディレクショナルライトで「Peter Panning」と「Shadow Acne」を補正する最適化スクリプトです。

light_lod_optimizer.gd

密集した環境にある OmniLight3D ノードのシャドウと可視性を、距離に基づいてカリングします。

reflection_probe_manager.gd

環境に大きな変化があった際、手動の「Update Once」トリガーを使用して ReflectionProbe をパフォーマンスに配慮しながら管理します。

spotlight_projector_setup.gd

Projector テクスチャを使って複雑なシャドウパターン（格子、ガラスのさざ波など）を再現する、高精細なライティングです。

light_volume_trigger.gd

洞窟と砂漠の切り替えには、Area3D駆動のカメラEnvironmentブレンドを使用します（環境リソースを複製し、露出／アンビエントをTweenで調整します）。

lighting_quality_manager.gd

実行時のRenderingServerプロファイルです。SDFGIの解像度を半分にし、シャドウアトラスのサイズとボリューメトリックフォグの密度を調整します。

---

DirectionalLight3D（太陽／月）

シャドウカスケード

# For outdoor scenes with camera moving from near to far
extends DirectionalLight3D

func _ready() -> void:
    shadow_enabled = true
    directional_shadow_mode = SHADOW_PARALLEL_4_SPLITS
    
    # Split distances (in meters from camera)
    directional_shadow_split_1 = 10.0   # First cascade: 0-10m
    directional_shadow_split_2 = 50.0   # Second: 10-50m
    directional_shadow_split_3 = 200.0  # Third: 50-200m
    # Fourth cascade: 200m - max shadow distance
    
    directional_shadow_max_distance = 500.0
    
    # Quality vs performance
    directional_shadow_blend_splits = true  # Smooth transitions

昼夜サイクル

必須 day_night_cycle.gd — ここに太陽のエネルギー／色の設定を再度記述しないでください。

---

OmniLight3D（ポイントライト）

omni_rangeは狭く保ち、二次減衰を優先してください。ちらつきやキャンプファイヤーのループはシーンスクリプトに記述し、この本文には記述しないでください。シャドウ付きOmniの数は厳格な予算上限です（「絶対に避ける」を参照）。

---

SpotLight3D（懐中電灯／ヘッドライト）

範囲、角度、プロジェクタークッキー、カメラ追従式懐中電灯には、必須のspotlight_projector_setup.gdを使用してください。Spotの設定をここに貼り付けないでください。

---

グローバルイルミネーション（スクリプト優先）

上記の基本方針表を使用してください。本文で判断する内容は次のとおりです。

パス	スクリプト	使用条件
屋内／密閉空間	必須 light_probe_manager.gd（＋lighting_manager.gd）	部屋ごとにVoxelGIの範囲を狭く設定します。壁を極端に薄くしないでください
屋外Forward+	必須 sdfgi_probe_manager.gd	リアルタイムGIを使用します。モバイル／互換性レンダラーでは読み込まないでください
静的／モバイル向けベイク	必須 lightmap_bake_helper.gd	LightmapGI＋シャドウマスキングを使用します。ベイクモードは非表示とは異なります
GIの予算がない場合	必須 fake_gi_bounce.gd	フィルライトのみを使用します

VoxelGI／SDFGI／Lightmapのプロパティ設定をここに再度記述しないでください。

---

EnvironmentとSky

Sky／アンビエント／トーンマップの切り替えには、必須のenvironment_blender.gdを使用してください。ボリューメトリックフォグ／光線には、必須のvolumetric_fx.gdを使用します（洞窟／森林ではvolumetric_fog_zones.gdも使用）。

純粋なライト予算／シャドウアトラス／カスケードの調整では、これらを読み込まないでください。light_lod_optimizer.gd／shadow_cascade_tuner.gdを使用してください。

---

ReflectionProbe

局所的な反射（鏡、光沢のある床）には、次を使用します。

# reflection_probe.gd
extends ReflectionProbe

func _ready() -> void:
    # Capture area
    size = Vector3(10, 5, 10)
    
    # Quality
    resolution = ReflectionProbe.RESOLUTION_512
    
    # Update mode
    update_mode = ReflectionProbe.UPDATE_ONCE  # Bake once
    # or UPDATE_ALWAYS for dynamic reflections (expensive)

---

パフォーマンス最適化

ライト予算

# Recommended limits:
# - DirectionalLight3D with shadows: 1-2
# - OmniLight3D with shadows: 3-5
# - SpotLight3D with shadows: 2-4
# - OmniLight3D without shadows: 20-30
# - SpotLight3D without shadows: 15-20

# Disable shadows on minor lights
@onready var candle_lights: Array = [$Candle1, $Candle2, $Candle3]

func _ready() -> void:
    for light in candle_lights:
        light.shadow_enabled = false  # Save performance

ライトごとのシャドウ距離

# Disable shadows for distant lights
extends OmniLight3D

@export var shadow_max_distance := 50.0

func _process(delta: float) -> void:
    var camera := get_viewport().get_camera_3d()
    if camera:
        var dist := global_position.distance_to(camera.global_position)
        shadow_enabled = (dist < shadow_max_distance)

---

エッジケース

床越しのシャドウ

# Problem: Thin floors let shadows through
# Solution: Increase shadow bias

extends DirectionalLight3D

func _ready() -> void:
    shadow_enabled = true
    shadow_bias = 0.1  # Increase if shadows bleed through
    shadow_normal_bias = 2.0

屋内シーンでの光漏れ

# Problem: VoxelGI light bleeds through walls
# Solution: Place VoxelGI nodes per-room, don't overlap

# Also: Ensure walls have proper thickness (not paper-thin)

---

エキスパート向けテクニックと最適化

1. 大規模な屋外シーンでのシャドウマスキング

遠方のオブジェクトにリアルタイムシャドウを描画するのはコストが高すぎます。LightmapGIのベイク時にDirectionalLight3DのベイクモードをDynamicに設定し、シャドウマスキングを使用してください。これにより、遠方のシャドウはテクスチャにベイクされ、近距離では動的オブジェクトがリアルタイムでシャドウを落とせるため、「二重シャドウ」のアーティファクトを防げます。

2. フェイクグローバルイルミネーション

GIをまったく使用できない場合（厳しいモバイル向け制約など）は、フェイクで表現しましょう。メインのDirectionalLight3Dを複製し、180度回転させて地面から上向きにし、シャドウをオフにして、Specularを0.0に設定し、Energyを10～40%に下げます。これにより、床からのバウンス光を低コストでシミュレートできます。

3. PCSS（接触硬化シャドウ）のシミュレーション

GodotのOmniLight3Dのスケーリングを利用すると、Percentage-Closer Soft Shadows（光源から離れるほどぼやけるシャドウ）をシミュレートできます。

extends OmniLight3D

func _ready() -> void:
    # Simulates area lights and Percentage-Closer Soft Shadows (PCSS).
    # Note: High performance cost. Keep the number of lights with light_size > 0.0 low.
    light_size = 0.5
    shadow_enabled = true
    
    # Distance fade culls the light and shadow completely when out of range,
    # preventing the clustered renderer from choking on too many overlapping PCSS lights.
    distance_fade_enabled = true
    distance_fade_begin = 20.0
    distance_fade_length = 5.0

---

エキスパート向けパターン：Light-Volume-Trigger

Area3DトリガーとTween駆動のCamera3Dオーバーライドを使用して、照明環境を滑らかに切り替えます（明るい砂漠から暗い洞窟に入る場合など）。

class_name LightVolumeTrigger extends Area3D

@export var interior_environment: Environment
@export var transition_duration: float = 2.0

func _ready() -> void:
    body_entered.connect(_on_body_entered)
    body_exited.connect(_on_body_exited)

func _on_body_entered(body: Node3D) -> void:
    if body.is_in_group("player"):
        var camera := get_viewport().get_camera_3d()
        # Duplicate to avoid modifying the original resource
        if not camera.environment:
            camera.environment = interior_environment.duplicate()
            
        var tween := create_tween().set_parallel(true)
        # Interpolate key properties for visual adaptation
        tween.tween_property(camera.environment, "tonemap_exposure", interior_environment.tonemap_exposure, transition_duration)
        tween.tween_property(camera.environment, "ambient_light_energy", interior_environment.ambient_light_energy, transition_duration)

func _on_body_exited(body: Node3D) -> void:
    if not body.is_in_group("player"):
        return
    var camera := get_viewport().get_camera_3d()
    if camera == null or camera.environment == null:
        return
    var world_env := get_tree().get_first_node_in_group("world_environment") as WorldEnvironment
    var target := world_env.environment if world_env and world_env.environment else Environment.new()
    var tween := create_tween().set_parallel(true)
    tween.tween_property(camera.environment, "tonemap_exposure", target.tonemap_exposure, transition_duration)
    tween.tween_property(camera.environment, "ambient_light_energy", target.ambient_light_energy, transition_duration)
    tween.chain().tween_callback(func():
        # Return to WorldEnvironment ownership when blend completes
        camera.environment = null
    )

ヒント

屋内にinterior = trueを設定したReflectionProbeを配置してください。プレイヤーの移動に合わせて、Godotが外部環境と自動的にブレンドします。

---

上級パターン：Interior-Mapping（Fake-Rooms）

ウィンドウの四角形ポリゴンに疑似的な奥行きを加える処理は、カスタムの空間シェーダーに関する専門分野です。プロジェクトのシェーダーで実装するか、godot-shaders-basics に引き継いでください。このスキル本文に未完成のレイボックスのスタブを残さないでください。

---

上級パターン：Lighting-Quality-Settings

RenderingServer API を使用してエンジンを直接制御し、実行時に複雑なライティング機能（Shadows、SDFGI、Fog）を管理します。

class_name LightingQualityManager extends Node

func apply_low_quality_profile(env_rid: RID) -> void:
    # 1. SDFGI Optimization
    # Huge performance gain: Render GI buffers at half resolution
    RenderingServer.gi_set_use_half_resolution(true)
    RenderingServer.environment_set_sdfgi_ray_count(RenderingServer.ENV_SDFGI_RAY_COUNT_4)
    RenderingServer.environment_set_sdfgi_frames_to_converge(RenderingServer.ENV_SDFGI_CONVERGE_IN_30_FRAMES)
    
    # 2. Shadow Optimization
    # Reduce global directional shadow atlas
    RenderingServer.directional_shadow_atlas_set_size(2048, true)
    RenderingServer.directional_soft_shadow_filter_set_quality(RenderingServer.SHADOW_QUALITY_SOFT_VERY_LOW)
    # Reduce positional (Omni/Spot) shadows for current viewport
    get_viewport().positional_shadow_atlas_size = 1024
    
    # 3. Volumetric Fog
    # Disable or heavily reduce fog detail
    RenderingServer.environment_set_volumetric_fog(env_rid, false, 0.01, Color.WHITE, Color.BLACK, 0.0, 0.2, 64.0, 2.0, 1.0, true, 0.9, 0.0, 1.0)

詳細なレシピ（必要に応じて）

トピック	リファレンス／スクリプト
VoxelGI／SDFGI／LightmapGI のセットアップ	gi-and-bake-recipes.md
Sky／fog／HDR 環境	environment-and-fog.md

リファレンス

段階的な情報開示：特定の API を調査する場合に限り公式ドキュメントのリンクを開き、関連スキルは近接するドメインに引き継ぐ場合に読み込んでください。関連スキル全体をあらかじめ読み込まないでください。

公式ドキュメント

• ライトとシャドウの概要 — Directional／Omni／Spot の役割、シャドウアトラスの予算、カスケード、プロジェクター、バイアスのトレードオフについて説明します。
• グローバルイルミネーションの概要 — ベイクまたは実行時のコストを決定する前に、LightmapGI、VoxelGI、SDFGI、プローブを比較する判断表です。
• SDFGI の使用 — Forward+ 専用のリアルタイム GI カスケード、オクルージョン、屋外や開放的なシーンで使用する品質設定について説明します。
• VoxelGI の使用 — 範囲が限定された屋内 GI、細分化、光漏れの原因（薄い壁）、部屋ごとのベイクワークフローについて説明します。
• LightmapGI の使用 — 静的ベイクモード、デノイザー、シャドウマスク、ベイク済みライティングでは動的ジオメトリに対応できない状況について説明します。
• リフレクションプローブ — 局所的なスペキュラーキャプチャ、Update Once と Always、環境を使った屋内ブレンディングについて説明します。
• グローバルイルミネーションの疑似表現 — SDFGI が利用できない Mobile および Compatibility 向けのフィルライト／バウンス近似について説明します。
• 環境とポストプロセッシング — 光量が変化する領域での WorldEnvironment のスカイ、アンビエント、トーンマップ、カメラのオーバーライドについて説明します。
• ボリュメトリックフォグとフォグボリューム — 光芒や局所的な雰囲気を表現する、グローバルなボリュメトリックフォグと FogVolume の密度ゾーンについて説明します。
• 物理ライトとカメラの単位 — 現実世界の昼夜や露出の連鎖に合わせる際の、ルクス／EV 形式のエネルギーについて説明します。
• 3D パフォーマンスの最適化 — ローカル LOD やカスケードの調整後もフレーム時間の目標を達成できない場合の、シャドウ／GI／ライト数の予算について説明します。
• AreaLight3D — Forward+ で発光のみの疑似表現の代わりに、パネルや画面に使用する矩形のソフトエリアライトについて説明します。

関連スキル

前提条件

• godot-project-foundations — レンダラーの選択（Forward+/Mobile/Compatibility）、シャドウアトラス、GI のプロジェクト設定によって、利用できるライティング機能が決まります。
• godot-3d-materials — Albedo/roughness/metallic/emission と gi_mode によって、表面がバウンスライトやベイク済みライトをどのように受けるかが決まります。
• godot-gdscript-mastery — マネージャーや環境ブレンドで使用する、型付きノードスクリプト、Tweens、Resource の所有権パターンについて説明します。

補完

• godot-shaders-basics — カスタムの spatial/fog/sky シェーダーやインテリアマッピングの手法によって、リアルライトを増やさずに Environment のライティングを拡張します。
• godot-camera-systems — 洞窟や屋内のライトボリューム遷移における、カメラの environment オーバーライドと露出の組み合わせについて説明します。
• godot-3d-world-building — シーンのスケール、密閉された屋内空間、GridMap/静的レイアウトによって、VoxelGI/LightmapGI をきれいにベイクできるようにします。
• godot-particles — フォグ密度とライトのエネルギーを合わせて設計しないと、ほこりや煙、火の粉が正しく見えません。
• godot-tweening — Area3D の境界で急に切り替えるのではなく、Environment、フォグ、ライトエネルギーを滑らかに遷移させます。
• godot-physics-3d — ライトボリュームやフォグゾーンのブレンドを制御する、Area3D のボディ進入／退出トリガーについて説明します。
• godot-adapt-desktop-to-mobile — Mobile/Compatibility を対象とする場合、SDFGI や負荷の高いシャドウを除去し、フェイクのバウンス GI に切り替えます。

下流／利用側

• godot-performance-optimization — カスケード分割、プローブ数、またはボリューメトリックフォグが引き続きプロファイラーの負荷を占める場合は、こちらを参照してください。
• godot-monte-carlo-balancer — ライティングの変更が戦闘、ステルス、ホラーの難易度に影響する場合、昼夜や暗闇の予算に応じた視認性／読みやすさをシミュレーションします。
• godot-genre-horror — 緊張感を重視した雰囲気づくりに、少数のライト、フォグ、屋内の ReflectionProbe を活用します。
• godot-debugging-profiling — シャドウアトラスや GI の負荷を確認してから、機能をむやみに削らずに済むよう、デバッガー／モニターの表示を使用します。

マスター

• godot-master — ライブラリのルーターであり、対応するモジュールのエントリーポイントです。複数の領域にまたがるライティングの課題を担当するドメインスキルを探す場合に参照してください。