2d-essentials

Godot 4.3+ の 2D 基本

すべての例は、非推奨 API を使用せず Godot 4.3+ を対象にしています。まず GDScript を示し、次に C# を示します。

関連スキル： CharacterBody2D の移動パターンについては player-controller、AnimatedSprite2D とスプライトアニメーションについては animation-system、コリジョンシェイプとレイキャストについては physics-system、Camera2D の追従と揺れについては camera-system、2D シェーダーとポストプロセスについては shader-basics、レンダリングとドローコールの調整については godot-optimization を参照してください。

---

1. キャンバスレイヤーと描画順序

描画順序のルール

単一のキャンバスレイヤー内では、ノードは シーンツリーの順序 で描画されます。シーンパネルで下に表示されるノードほど、手前に描画されます。ツリーを並べ替えずに上書きするには、z_index を使用します。

# Draw this node above siblings (default z_index is 0)
z_index = 10

# z_index is relative to the parent by default (z_as_relative = true);
# set it false to make this node's z_index absolute
z_as_relative = false

CanvasLayer

CanvasLayer は独自のトランスフォームを持つ別個のレンダリングレイヤーを作成し、カメラから独立させます。layer の値が大きいほど手前に描画されます。

レイヤー	一般的な用途
-1	視差背景
0	デフォルトのゲームレイヤー（CanvasLayer を持たないすべての Node2D）
1	HUD／UI オーバーレイ
2	ポーズメニュー、画面遷移

# Scene tree example
Main
├── ParallaxBackground (CanvasLayer, layer = -1)
│   └── Parallax2D (follow_viewport = false — the layer doesn't follow the camera)
├── World (Node2D — default layer 0)
│   ├── TileMapLayer
│   └── Player
└── HUD (CanvasLayer, layer = 1)
    └── Control

注意： 描画順序の制御に CanvasLayer は必須ではありません。同じゲームワールド内のオブジェクトには、z_index またはシーンツリーの順序を使用してください。CanvasLayer は、カメラから独立させる要素（HUD、視差、画面遷移）に使用します。

キャンバストランスフォーム

Camera2D はビューポートの canvas_transform を変更して動作します。手動で制御する場合：

# Scroll the canvas directly (equivalent to camera movement)
get_viewport().canvas_transform = Transform2D(0, Vector2(-200, 0))

座標変換

# Local to canvas (world) coordinates
var world_pos: Vector2 = get_global_transform() * local_pos
var local_pos: Vector2 = get_global_transform().affine_inverse() * world_pos

# Local to screen coordinates (accounts for camera, stretch, window)
var screen_pos: Vector2 = get_viewport().get_screen_transform() * get_global_transform_with_canvas() * local_pos

// Local to canvas (world) coordinates
Vector2 worldPos = GetGlobalTransform() * localPos;
Vector2 localFromWorld = GetGlobalTransform().AffineInverse() * worldPos;

// Local to screen coordinates
Vector2 screenPos = GetViewport().GetScreenTransform() * GetGlobalTransformWithCanvas() * localPos;

---

2. TileMap システム

TileMapLayer（Godot 4.3+）は最新の API です。1 つのタイルマップが 1 つのノード、つまり 1 つのレイヤーになります。TileSet リソース（アトラス＋プロパティ＋物理＋カスタムデータ）を使ってタイルを配置します。バイオームに応じたタイル選択には 地形オートタイル を、タイル上にシーンインスタンスを配置するには シーンコレクションタイル を使用します。

TileSet の設定、アトラス／物理／地形の構成、タイルのカスタムデータ、シーンコレクションタイル、および 4.5+ のタイル衝突バンプの自動マージ修正については、references/tilemap.md を参照してください。

---

3. 視差スクロール

Parallax2D（Godot 4.3+）は、旧式の ParallaxBackground／ParallaxLayer の組み合わせに代わるものです。各レイヤーの scroll_scale を設定します（0 = 静止、1 = カメラに 1:1 で追従、小数値 = 奥行き表現）。無限にタイル状に繰り返すには repeat_size を追加します。

Parallax2D の設定、横スクロールアクションのレイヤー例、無限リピート、画面分割時の視差、よくある間違いについては、references/parallax.md を参照してください。

---

4. 2D ライトと影

PointLight2D と DirectionalLight2D はスプライトに光を当てます。ノーマルマップと組み合わせて 3D 風のシェーディングを行うか、フラットなスプライトに加算ブレンドの照明を使用します。LightOccluder2D で影を落とせます。

ノードの概要、PointLight2D のプロパティ、影の設定、カリングマスク、オクルーダー、2D ノーマルマップ、ピクセルアートのライティングのヒント、加算スプライトによる疑似ライトのテクニックについては、references/lights-and-shadows.md を参照してください。

---

5. 2D パーティクルシステム

大量のパーティクル（50 個以上、GPU 駆動）には GPUParticles2D を、少量のパーティクルや GPU 非対応プラットフォームには CPUParticles2D を使用します。GPUParticles2D は ParticleProcessMaterial で駆動します。CPUParticles2D は同じパラメーターを独自のプロパティとして公開します。

GPU と CPU の選択基準、基本設定、ParticleProcessMaterial の 2D プロパティ、テクスチャからの放出、フリップブック、可視範囲矩形、2D でよく使われるレシピについては、references/2d-particles.md を参照してください。

---

6. カスタム描画

任意の CanvasItem で _draw() をオーバーライドすると、線、ポリゴン、テキスト、任意の形状を描画できます。再レンダリングを実行するには queue_redraw() を呼び出します（_draw() を直接呼び出してはいけません）。

_draw() メソッド、再描画のパターン、描画メソッドの完全なリファレンス、デフォルトフォントの使い方、@tool によるエディタープレビュー、線幅に関する注意点については、references/custom-drawing.md を参照してください。

Godot 4.7 以降： 実行時に描画可能なテクスチャ型である DrawableTexture2D は、4.7 で実験的機能としてリリースされました。まだ本番環境での使用は推奨されていません。

---

7. 2D メッシュ

使用する場面

大きな透明領域によって GPU のフィルレートが無駄になる場合、MeshInstance2D は Sprite2D の代わりになります。GPU は完全に透明なピクセルを含むテクスチャ全体の四角形を描画しますが、メッシュを使えばそのようなピクセルを除外できます。

Sprite2D を MeshInstance2D に変換する

1. Sprite2D を選択します
2. メニューから Sprite2D → Convert to MeshInstance2D を選択します
3. 拡張と簡略化のパラメーターを調整します
4. 「Convert 2D Mesh」をクリックします

特に適した対象：

• 透明部分のある画面サイズの画像
• 形状が不規則な視差レイヤー
• 透明な余白が大きいレイヤー画像
• モバイル／ローエンド GPU 向けのプロジェクト

---

8. 2D アンチエイリアス

ノードごとのアンチエイリアス（推奨）

多くの描画メソッドは antialiased パラメーターに対応しています。

draw_line(Vector2.ZERO, Vector2(100, 50), Color.WHITE, 2.0, true)  # antialiased = true

// Equivalent in a CanvasItem subclass (e.g., a custom Control or Node2D):
public override void _Draw()
{
    DrawLine(new Vector2(0, 0), new Vector2(100, 50), Colors.White, width: 2.0f, antialiased: true);
}

Line2D には antialiased プロパティ（C#：Antialiased）がありますが、Line2D はこの値を保持するだけで描画呼び出しに渡さないため、見た目には反映されません。Line2D のエッジを滑らかにするには、MSAA 2D（下記）を使うか、エッジがソフトなテクスチャを使用してください。

⚠️ Godot 4.7 での変更点： CanvasItem のアンチエイリアス付き線描画では、アンチエイリアスのフェザーが追加されなくなりました。フェザーによって draw_line() のような線が意図したより太く見えていたため、アップグレード後はアンチエイリアス付きの線が細く描画されます。以前の見た目に依存していたプロジェクトでは、より大きな width を指定する必要があります。4.7 移行ガイドを参照してください。

MSAA 2D

Forward+ および Mobile レンダラーでのみ使用できます（Compatibility では使用できません）。

Project Settings → Rendering → Anti Aliasing → Quality → MSAA 2D

レベル：2x、4x、8x。

MSAA の対象	MSAA の対象外
ジオメトリーのエッジ（線、ポリゴン）	ニアレストネイバーのテクスチャ内のエイリアシング
テクスチャのエッジに接するスプライトのエッジ	カスタム 2D シェーダーの出力
	フォントの描画
	Light2D によるスペキュラーエイリアシング

ピクセルアートの場合： MSAA 2D を有効にしないでください。意図的にシャープにしたエッジがぼやけます。ノードごとの antialiased パラメーターを必要な箇所に限定して使用してください。

---

9. 2D スナップとピクセルパーフェクト

エディターでのスナップ

2D ツールバーの三点メニュー：

• グリッドステップ — グリッドにスナップします（Grid Offset と Step を設定）
• 回転ステップ — 回転を角度単位でスナップします
• スマートスナップ — 親、ノードのアンカー、辺、中心、ガイドにスナップします

実行時のピクセルスナップ

ピクセルアートのゲームでは、サブピクセルの揺れを防ぐためにピクセルスナップを有効にします。

• Node2D： Project Settings → Rendering → 2D → Snapping → Snap 2D Transforms to Pixel
• 頂点： Project Settings → Rendering → 2D → Snapping → Snap 2D Vertices to Pixel
• Controls： Project Settings → GUI → General → Snap Controls to Pixels

---

10. 実装チェックリスト

• 2D ライティングを受けられるように、背景を Sprite2D または ColorRect にします（デフォルトのクリアカラーは使用しません）
• TileSet を外部 .tres リソースとして保存し、各レベルで再利用できるようにします
• テクスチャのにじみを防ぐため、TileSet で Use Texture Padding を有効にします
• Parallax2D テクスチャの左上が中央ではなく (0,0) になっていることを確認します
• repeat_size を実際のテクスチャサイズに合わせます
• カメラをズームアウトできる場合は、repeat_times を増やします
• 影を有効にする場合は、影を落とすオブジェクトに LightOccluder2D ノードを追加します
• 不要なライティング計算を避けるため、ライトとオクルーダーのカリングマスクを設定します
• GPUParticles2D に有効な Visibility Rect が設定されていることを確認します（Particles メニューから自動生成できます）
• カスタム描画の状態が変わったときに queue_redraw() を呼び出します
• タイルのコリジョン形状には、手動で CollisionShape2D ノードを追加するのではなく、Physics Layer システムを使用します
• モバイルまたはローエンドのターゲットでは、大きな透明スプライトを MeshInstance2D に変換します