assets-pipeline

Godot 4.3+ のアセットパイプライン

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

関連スキル： オーディオ再生とバス構成については audio-system、3D マテリアルとライティングについては 3d-essentials、2D レンダリングとスプライトについては 2d-essentials、インポートしたアニメーションについては animation-system、アセットに関連するパフォーマンスについては godot-optimization、スレッドを使用したリソース読み込みについては multithreading を参照してください。

---

1. インポートの仕組み

インポートシステム

ファイルを res:// に追加すると、Godot はファイルの種類に応じて自動的にインポートします。インポート設定は、元のファイルと同じ場所にあるサイドカーファイル .import に保存されます。

project/
├── textures/
│   ├── player.png           ← original file (committed to VCS)
│   └── player.png.import    ← import settings (committed to VCS)
└── .godot/
    └── imported/            ← compiled cache (NOT committed — .gitignore it)

主なルール

• .godot/imported/ 内のファイルは変更しないでください — 元のファイルから再生成されます
• .import ファイルはバージョン管理にコミットしてください — 設定が保存されています
• 設定を変更した後は再インポートしてください：ファイルを選択 → Import ドック → Reimport をクリック
• .godot/ は .gitignore に含めてください

インポート設定の変更

1. FileSystem ドックでファイルを選択します
2. Import ドックを開きます（デフォルトでは Scene ドックの隣にあります）
3. 設定を変更します
4. Reimport をクリックします（複数の変更をまとめて適用する場合は Reimport All）

3D シーンでは、Advanced Import Settings からインポート設定を行うこともできます（.glb／.gltf ファイルをダブルクリックします）。

---

2. 画像のインポート

圧縮モード

モード	品質	VRAM	ファイルサイズ	用途
Lossless	完全	高	大	ピクセルアート、UI 要素
Lossy	良好	高	小	大きな写真、背景
VRAM Compressed	低下	低	小	3D テクスチャ、大きな 2D スプライト
VRAM Uncompressed	完全	高	大	VRAM 圧縮によるアーティファクトが許容できない場合
Basis Universal	低下	低	非常に小	クロスプラットフォーム、複数の GPU フォーマット

各モードの用途

Pixel art / UI icons       → Lossless (no artifacts, crisp pixels)
2D game sprites            → Lossless (small sprites) or VRAM Compressed (large sprites)
3D textures (albedo, normal) → VRAM Compressed (saves GPU memory)
Large backgrounds          → Lossy or VRAM Compressed
Mobile targets             → VRAM Compressed (essential for memory)

主なインポート設定

設定	説明	デフォルト
Compress > Mode	圧縮アルゴリズム（上の表を参照）	Lossless（3D プリセットでは VRAM Compressed。3D 用と判定されたテクスチャにはこの設定が適用されます）
Mipmaps > Generate	距離に応じたレンダリング用にミップマップを生成します	Off（3D プリセットでは On）
Process > Fix Alpha Border	透明なスプライトに暗い輪郭ができるのを防ぎます	On
Process > Premult Alpha	アルファ値を事前乗算します（暗いハローを防ぎます）	Off

Godot 4 では、フィルタリングとリピートはインポートオプションではありません。各 CanvasItem の texture_filter／texture_repeat（3D ではマテリアルのサンプラー）で設定します。

ピクセルアートの設定

鮮明なピクセルアートにするには、プロジェクト全体の設定を変更します。

Project Settings > Rendering > Textures > Canvas Textures > Default Texture Filter → Nearest

またはノードごとに設定します：CanvasItem.texture_filter → Nearest

ミップマップの有効化

ミップマップを使用すると、斜めや遠距離から見たテクスチャのちらつきを防げます。3D テクスチャでは必須、2D テクスチャでは任意です。

• 3D テクスチャ： 常にミップマップを有効にします（Import ドック → Mipmaps → Generate → On）
• 2D スプライト： 通常はオフです（Camera2D のズームを使用する場合を除く）
• UI テクスチャ： オフです（固定倍率で描画されます）

Godot 4.7+： DDS のインポートで R8 および R8G8 テクスチャ形式がサポートされます。(GH-116307)

---

3. 3D シーンのインポート

対応フォーマット

フォーマット	拡張子	推奨
glTF	.gltf, .glb	推奨 — オープン標準で、最も優れたサポートに対応
Blend	.blend	Blender から直接インポートできます（Blender のインストールが必要です）
FBX	.fbx	レガシーなパイプラインに適しています
Collada	.dae	古いフォーマットです。可能であれば glTF を使用してください
OBJ	.obj	静的メッシュのみ — アニメーション／リグには対応していません

推奨フォーマットは glTF です。 Godot のサポートが最も優れており、オープン標準で、マテリアル、アニメーション、リグを正確に保持します。

ノードの命名規則

Godot は、3D モデルのオブジェクト名に含まれるサフィックスに基づいて、適切なノードタイプを自動的に作成します。

サフィックス	生成されるノード	名前の例
-col	StaticBody3D + 衝突形状	Wall-col
-convcol	ConvexPolygonShape3D	Rock-convcol
-rigid	RigidBody3D	Barrel-rigid
-navmesh	NavigationRegion3D	Floor-navmesh
-occ	OccluderInstance3D（-occonly はメッシュを破棄します）	BigWall-occ

In Blender:                  In Godot (after import):
Wall-col (mesh object)    →  Wall (MeshInstance3D)
                               └── StaticBody3D
                                   └── CollisionShape3D (auto-generated)

インポートドックの設定

FileSystem でインポートした .glb／.gltf を選択し、インポートドックで設定します。

設定	説明
Root Type	ルートノードのタイプを上書きします（Node3D、RigidBody3D など）
Root Name	ルートノードのカスタム名
Meshes > Generate LOD	LOD レベルを自動生成します（デフォルトで有効）
Meshes > Light Baking	ライトマップのベイクに Static または Dynamic を指定します
Animation > Import	アニメーションのインポートを有効／無効にします
Animation > FPS	このフレームレートでアニメーションをベイクします

Godot 4.7 以降： インポートドックのインポートタイプオプションでは、3D シーンファイルを完全なシーンとしてではなく、単一の Mesh リソースまたは MeshLibrary（GridMap 用）としてインポートすることもできます。3D オーサリングツールで別途エクスポートする必要はありません。(GH-107856)

⚠️ Godot 4.7 での変更点： EditorSceneFormatImporter の IMPORT_SCENE、IMPORT_ANIMATION、IMPORT_FAIL_ON_MISSING_DEPENDENCIES、IMPORT_GENERATE_TANGENT_ARRAYS、IMPORT_USE_NAMED_SKIN_BINDS、IMPORT_DISCARD_MESHES_AND_MATERIALS、および IMPORT_FORCE_DISABLE_MESH_COMPRESSION 定数は、新しい ImportFlags 列挙型（ビットフィールド）に移動しました。GDScript との互換性は維持されています。古いクラスレベル定数を参照する C# インポータープラグインは、列挙型のメンバーに切り替える必要があります。4.7 移行ガイドを参照してください。

実行時のシーン読み込み

コンパイル時にパスがわかっている場合は preload() を、データ駆動のパスには load() を使用します。GDScript と C# のスニペット：references/runtime-resource-loading.md。

実行時の glTF インポートフラグ（Godot 4.7 以降）

GLTFDocument は ImportFlags ビットフィールドを公開します。IMPORT_FLAG_GENERATE_TANGENT_ARRAYS（8）、IMPORT_FLAG_USE_NAMED_SKIN_BINDS（16）、IMPORT_FLAG_DISCARD_MESHES_AND_MATERIALS（32）、IMPORT_FLAG_FORCE_DISABLE_MESH_COMPRESSION（64）は、append_from_file()、append_from_buffer()、および append_from_scene() の flags: int = 0 パラメーターで受け付けられます。

var doc := GLTFDocument.new()
var state := GLTFState.new()
doc.append_from_file("user://mods/enemy.glb", state,
        GLTFDocument.IMPORT_FLAG_GENERATE_TANGENT_ARRAYS | GLTFDocument.IMPORT_FLAG_USE_NAMED_SKIN_BINDS)
add_child(doc.generate_scene(state))

var doc = new GltfDocument();
var state = new GltfState();
doc.AppendFromFile("user://mods/enemy.glb", state,
    (uint)(GltfDocument.ImportFlags.GenerateTangentArrays | GltfDocument.ImportFlags.UseNamedSkinBinds));
AddChild(doc.GenerateScene(state));

---

4. アニメーションのインポート

アニメーションの分割

3D ファイルに複数のアニメーションを含む単一のタイムラインがある場合は、詳細インポート設定で分割します。

1. .glb ファイルをダブルクリックして、詳細インポート設定を開きます
2. Animations タブに移動します
3. 開始フレームと終了フレームを指定して、アニメーションクリップを追加します
4. クリップごとにループモード（None、Linear、Ping-Pong）を設定します

アニメーションのリターゲティング

異なるスケルトンを持つキャラクター間でアニメーションを共有します。

1. ソース（アニメーション）モデルとターゲット（キャラクター）モデルの両方をインポートします
2. ターゲットモデルで詳細インポート設定を開きます
3. Skeleton3D > Retarget設定に移動します
4. ソースのボーンをターゲットのボーンにマッピングします
5. 標準的な人型マッピングにはSkeletonProfileリソースを使用します

アニメーションのインポート設定

設定	説明
インポート	アニメーションのインポートを有効／無効にします
FPS	ベイクするフレームレート（標準は30）
トリミング	開始／終了時の空フレームを削除します
不変トラックを削除	変化しないトラックを削除します

---

5. オーディオのインポート

オーディオ再生、バス設定、音楽管理について詳しくは、audio-systemスキルを参照してください。

推奨フォーマット

フォーマット	インポート形式	用途	主な設定
WAV	AudioStreamWAV	短い効果音	Loop Mode、Max Rate
OGG	AudioStreamOggVorbis	音楽、長い効果音	Loop、Loop Offset
MP3	AudioStreamMP3	音楽（代替）	Loop、BPM

主なインポート設定

設定	説明	使用する場面
Loop	ループ再生を有効にします	音楽、環境音のループ
Loop Offset	ループ再開時の開始位置	ループ時にイントロを避ける
Force Mono（WAVのみ）	ステレオをモノラルに変換します	3Dの位置音響
BPM	1分あたりの拍数	リズムゲーム
Beat Count	トラックの総拍数	リズム同期

インポートのヒント： 短い効果音にはWAVを使用してください（PCMはデコードコストがかかりません。4.4以降では、デコードコストの低いQOAとしてWAVをインポートするのがデフォルトです）。音楽にはOGGを使用してください（ファイルサイズが小さく、品質も良好です）。AudioStreamPlayer3Dで使用するオーディオにはモノラルファイルを使用してください（WAVの場合はForce Mono）。ステレオは適切に空間化されません。

---

6. リソース形式

.tresと.resの比較

形式	種類	読み取り可能	用途
.tres	テキスト	はい	手作業で編集する、または差分を確認するリソース
.res	バイナリ	いいえ	大容量のリソース、読み込みの高速化

# Save as text resource
ResourceSaver.save(my_resource, "res://data/item.tres")

# Save as binary resource
ResourceSaver.save(my_resource, "res://data/item.res")

# Load (either format)
var resource: Resource = load("res://data/item.tres")

ResourceSaver.Save(myResource, "res://data/item.tres");
ResourceSaver.Save(myResource, "res://data/item.res");
var resource = GD.Load<Resource>("res://data/item.tres");

使い分け

• .tres — 作成・編集するカスタムリソース（アイテムデータ、設定、スキル定義）。バージョン管理に適しています。
• .res — 生成されたデータや大容量のバイナリデータ（ベイク済みライトマップ、ナビゲーションメッシュ、大きなメッシュ）。読み込みが速くなります。
• .tscn — テキスト形式のシーンファイル（シーンには常にテキスト形式を使用します。VCSで差分を確認できます）
• .scn — バイナリ形式のシーンファイル（まれに使用します。読み込み時間が重要となる非常に大きなシーンに限ります）

スレッドを使用したリソース読み込み

ResourceLoader.load_threaded_request() / load_threaded_get_status() / load_threaded_get()のパターンを使うと、ゲームをフリーズさせずに大容量のリソースを読み込めます。読み込み画面の詳しい実装例（GDScript + C#）については、references/runtime-resource-loading.mdを参照してください。

---

7. よくある問題

症状	原因	対処方法
テクスチャがぼやけて見える	ピクセルアートに Linear フィルターが設定されている	Project Settings で Default Texture Filter を Nearest に設定します
透過スプライトに暗い輪郭がある	インポート時にアルファ境界が修正されていない	Import ドックで「Fix Alpha Border」を有効にします
3D モデルにコリジョンがない	ソースモデルに命名サフィックスがない	Blender でメッシュ名に -col サフィックスを追加するか、手動で追加します
インポートしたアニメーションが見つからない	Import ドックで「Import Animation」が無効になっている	Animation > Import を有効にして再インポートします
モバイルでテクスチャの VRAM 使用量が多すぎる	大きなテクスチャに Lossless 圧縮を使用している	256px を超えるテクスチャには VRAM Compressed に切り替えます
3D テクスチャが遠くでちらつく	ミップマップが生成されていない	Import ドックで Mipmaps > Generate を有効にします
オーディオのループ位置でポップ音やクリック音がする	ループオフセットが正しく設定されていない	Import ドックで Loop Offset を調整し、オーディオエディターでフェードを追加します
シーンファイルが非常に大きい	テキスト形式の .tscn ではなくバイナリ形式の .scn を使用している	VCS ではシーンを .tscn として保存し、必要な場合にのみ .scn を使用します
再クローン後にインポート設定が失われる	.import ファイルが VCS にコミットされていない	.import ファイルは必ずコミットし、.gitignore に含めるのは .godot/ のみとします
スレッド読み込みでゲームがフリーズする	load() を使って毎フレーム状態を確認している	ResourceLoader.load_threaded_request/get_status のパターンを使用します

⚠️ Godot 4.7 での変更点： フォントインポートの hinting のデフォルトが 1（Light）から 3（Light (Except Pixel Fonts)）に変更されました。新しくインポートしたピクセルスタイルのフォントでは、ヒンティングが自動的に無効になります。インポート済みのフォントでは、.import ファイルに保存されている hinting=1 が維持されます。新しいフォント、または .import が再生成されたフォントのみ、新しいデフォルトが適用されます。4.6 と同じ設定にするには、Import ドックで hinting を 1（Light）に設定します。4.7 migration guideを参照してください。

---

8. 実装チェックリスト

• .gitignore では .godot/ を除外し、.import ファイルは除外しない
• ピクセルアートのプロジェクトでは、Project Settings で Default Texture Filter を Nearest に設定する
• 3D テクスチャではミップマップを有効にする（Import ドック → Mipmaps → Generate）
• 大きなテクスチャでは VRAM Compressed を使用する（特にモバイル向けの場合）
• 3D モデルでは、主要なインポート形式として glTF 形式（.glb または .gltf）を使用する
• コリジョンシェイプでは、3D オーサリングツールで命名サフィックス（-col、-convcol）を使用する
• Advanced Import Settings でアニメーションを個別のクリップに分割する
• オーディオ SFX には WAV、音楽には OGG Vorbis を使用する
• 3D 位置オーディオファイルはモノラルにする（WAV インポートで Force Mono を有効にする）
• カスタムデータリソースには、バージョン管理で差分を確認しやすい .tres（テキスト）を使用する
• 大きなリソースや実行時に読み込むリソースには ResourceLoader.load_threaded_request() を使用する
• バージョン管理ではシーンファイルに .tscn（テキスト形式）を使用する