godot-3d-essentials

Godot 3D Essentials（4.x）

トランスフォーム、カメラ、ライト、環境／ポストプロセス、マテリアル、GridMap によるブロックアウトを組み合わせて、動作する3Dシーンを構築します。対象は Godot 4.7 です。

使用する場面

• 3Dシーンの作成や修正を始めるときに使用します。Camera3D の配置、ライトの追加、WorldEnvironment（スカイ、アンビエント、トーンマップ、グロー／SSAO）の設定、マテリアルの割り当て、GridMap を使ったレベルの構築などが該当します。

使用しない場面： 空間シェーダーの作成 → godot-shaders；3D物理ボディとレイキャスト → godot-physics；キャラクターアニメーションのブレンディング → godot-animation；完全なFPSテンプレート → fps-shooter ジャンルスキル。

基本的なワークフロー

1. 3Dの要素はすべて Node3D であり、Transform3D（位置、回転の基底、スケール）を持ちます。global_position で移動し、rotate_y(angle) または look_at(target) で回転します。
2. Camera3D を追加します。 current に設定するか、make_current() を呼び出し、fov、near、far を設定します。オービットカメラや追従カメラでは、リグ／ピボットを親に設定します。
3. シーンにライトを当てます。 DirectionalLight3D は太陽光で、OmniLight3D／SpotLight3D はローカルライトです。ライトごとにシャドウを有効にします。ライトとアンビエントがないと、サーフェスは黒く描画されます。
4. Environment リソースを使って WorldEnvironment を追加します。 背景（スカイ／カラー）、アンビエントライト、トーンマップ、ポストプロセス（グロー、SSAO、フォグ、調整）を設定します。
5. MeshInstance3D にマテリアルを設定します（StandardMaterial3D または ShaderMaterial）。
6. GridMap でレベルをブロックアウトします。 3Dグリッド上に MeshLibrary のアイテムを配置します（タイルマップの3D版です）。

パターン

1. 追従カメラ（サードパーソン、スムーズ追従）

extends Camera3D

@export var target: Node3D
@export var offset := Vector3(0, 4, 8)
@export var smooth := 6.0

func _physics_process(delta: float) -> void:
    if target == null:
        return
    var desired := target.global_position + offset
    global_position = global_position.lerp(desired, smooth * delta)  # smooth follow
    look_at(target.global_position, Vector3.UP)                      # face the target

2. コードで設定する太陽光と環境

func _ready() -> void:
    var sun := DirectionalLight3D.new()
    sun.rotation_degrees = Vector3(-45, -30, 0)
    sun.shadow_enabled = true
    add_child(sun)

    var we := WorldEnvironment.new()
    var env := Environment.new()
    env.background_mode = Environment.BG_SKY
    env.sky = Sky.new()
    env.sky.sky_material = ProceduralSkyMaterial.new()
    env.ambient_light_source = Environment.AMBIENT_SOURCE_SKY
    env.tonemap_mode = Environment.TONE_MAPPER_FILMIC
    env.glow_enabled = true
    we.environment = env
    add_child(we)

3. コードで StandardMaterial3D を割り当てる

func tint_mesh(mesh: MeshInstance3D, color: Color) -> void:
    var mat := StandardMaterial3D.new()
    mat.albedo_color = color
    mat.metallic = 0.0
    mat.roughness = 0.6
    mat.emission_enabled = true
    mat.emission = color * 0.3
    mesh.material_override = mat       # overrides the mesh's surface materials

4. GridMap にタイルを配置する

@onready var grid: GridMap = $GridMap   # cell_size + mesh_library set in the editor

func build_floor(width: int, depth: int, item_id: int) -> void:
    for x in width:
        for z in depth:
            # set_cell_item(Vector3i cell, int item, orientation = 0)
            grid.set_cell_item(Vector3i(x, 0, z), item_id)

注意点

• シーンが黒く描画される → ライトとアンビエントがありません。DirectionalLight3D や、アンビエント／スカイを設定した WorldEnvironment を追加します。新しいシーンには、どちらもデフォルトで設定されていません。
• カメラがない／カメラが違う。 何も表示されない場合は、Camera3D が current になっていません。current = true に設定するか make_current() を呼び出します。1つのビューポートで描画されるカメラは1つだけです。
• ローカルトランスフォームとグローバルトランスフォームの混同。 position／rotation は親を基準とし、global_position／global_transform はワールド空間での値です。回転した親の下で混在させると、予想外の結果になります。look_at ではグローバル座標を使用します。
• 物理オブジェクト／ライトのスケーリング。 Node3D に不均一な scale を設定すると、子のコリジョンやライトが歪みます。メッシュアセットをスケーリングするか、均一なスケールを使用してください。
• look_at の from／up を忘れる。 look_at(target, up) では、target がノードの位置と等しい場合や、up が視線方向と平行な場合に、NaN や反転が発生します。
• MeshLibrary のない GridMap は何も配置しません。MeshLibrary（シーンから作成）を作成して割り当てます。set_cell_item(cell, -1) はセルをクリアします。
• HDR／グローが強すぎる → tonemap_mode とグローのしきい値を確認します。フィルミックトーンマッピングでは、生のエミッシブ値によって強いブルームが発生します。

参考資料

• Transform3D の計算、カメラの投影モード、ライト／シャドウのパラメーター、Environment／ポストプロセスのすべてのオプション、MeshLibrary の作成、ReflectionProbe／LightmapGI によるライティングについては、references/scene-and-environment.md を参照してください。

関連スキル

• godot-physics — 3Dボディ、エリア、レイキャスト。
• godot-shaders — カスタム3Dサーフェス向けの空間シェーダー。
• godot-animation — 3Dキャラクター向けの AnimationTree。
• camera-systems — サードパーソンのオービット／ファーストパーソンの視点リグ、フレーミング、衝突。
• performance-optimization — 3Dシーンをフレーム予算内に維持します（ドローコール、ライト、LOD）。
• fps-shooter — 3Dの移動、入力、AIを組み合わせてゲームを作成します。