defold-proto-file-editing

Defold Proto Text Format ファイルの編集

Protobuf Text Format を使用する Defold のリソースファイルとコンポーネントファイルを作成、編集します。

使用するタイミング

このスキルは、Protobuf Text Format としてシリアライズされるすべての Defold ファイル形式を対象とします。Lua スクリプトファイル（.script、.gui_script、.render_script、.editor_script）は対象外です。

対応ファイル形式

フィールドの詳細なリファレンスについては、references/ にある各形式のリファレンスファイルを参照してください。

• references/collection.md — .collection ファイル（ゲームレベル、階層構造）
• references/gameobject.md — .go ファイル（ゲームオブジェクトのプロトタイプ）
• references/gui.md — .gui ファイル（GUI シーン）
• references/atlas.md — .atlas ファイル（テクスチャアトラス）
• references/sprite.md — .sprite ファイル（スプライトコンポーネント）
• references/collisionobject.md — .collisionobject ファイル（物理演算）
• references/convexshape.md — .convexshape ファイル（外部の凸包衝突形状）
• references/label.md — .label ファイル（ゲーム空間内のテキスト）
• references/font.md — .font ファイル（フォントリソース）
• references/material.md — .material ファイル（レンダリングマテリアル）
• references/model.md — .model ファイル（3D モデル）
• references/mesh.md — .mesh ファイル（バッファデータから作成するカスタム 3D メッシュ）
• references/particlefx.md — .particlefx ファイル（パーティクルエフェクト）
• references/sound.md — .sound ファイル（オーディオ）
• references/camera.md — .camera ファイル（カメラコンポーネント）
• references/factory.md — .factory ファイル（オブジェクトの生成）
• references/collectionfactory.md — .collectionfactory ファイル（コレクションの生成）
• references/collectionproxy.md — .collectionproxy ファイル（ワールドの読み込み）
• references/tilemap.md — .tilemap ファイル（タイルグリッド）
• references/tilesource.md — .tilesource ファイル（タイルソースリソース）
• references/objectinterpolation.md — .objectinterpolation ファイル（拡張機能：固定ステップ移動の補間）

スキルの保守作業（リファレンスの更新、proto スキーマの取得）には、defold-skill-maintain スキルを使用してください。

シェーダーとマテリアルの関係

シェーダー（.vp、.fp、.glsl）は GLSL ファイルであり、このスキルの対象外です。シェーダーファイルには defold-shaders-editing スキルを使用してください。ただし、シェーダーとマテリアルは密接に連携しています。

マテリアルからシェーダーへのデータフロー

1. 定数：vertex_constants / fragment_constants で宣言した定数は、シェーダー内の uniform 変数になります。エンジンが提供する定数（CONSTANT_TYPE_VIEW、CONSTANT_TYPE_PROJECTION など）は自動的に設定されます。ユーザー定数（CONSTANT_TYPE_USER）は go.set() / go.animate() でアニメーションさせることができます。

2. サンプラー：samplers で宣言したサンプラーは、sampler2D の uniform になります。マテリアル内のサンプラーの name は、シェーダー内の uniform 名と一致している必要があります。

3. 属性：attributes で宣言した属性は、頂点 in 変数になります。SEMANTIC_TYPE_POSITION、SEMANTIC_TYPE_TEXCOORD などのセマンティック型は、エンジンが生成するデータを提供します。

mtx_world と mtx_normal によるインスタンシング

インスタンス描画では、マテリアルの attributes セクションで宣言しなくても、次の 2 つの特殊な頂点属性を使用できます。

• mtx_world — mat4 のワールド変換行列（インスタンスごと）
• mtx_normal — mat4 の法線変換行列（インスタンスごと）

これらをシェーダー内で頂点 in 属性として宣言すると、Defold はインスタンス描画を自動的に有効にします。

// model_instanced.vp
in mediump mat4 mtx_world;
in mediump mat4 mtx_normal;

void main() {
    vec4 p = mtx_view * mtx_world * vec4(position.xyz, 1.0);
    var_normal = normalize((mtx_normal * vec4(normal, 0.0)).xyz);
    gl_Position = mtx_proj * p;
}

インスタンシングの要件：

• マテリアルの vertex_space が VERTEX_SPACE_LOCAL であること
• シェーダーで mtx_world および／または mtx_normal を in 属性として宣言すること
• これらをマテリアルの attributes リストに追加する必要はありません

参考例

組み込みシェーダーの例は .deps/builtins/materials/ にあります。

• sprite.vp / sprite.fp — 2D スプライトの描画（ワールド空間）
• model.vp / model.fp — 3D モデルの描画（ローカル空間、uniform）
• model_instanced.vp — インスタンシングを使用した 3D モデル（mtx_world、mtx_normal を属性として使用）

同梱スクリプト

• scripts/get_image_size.py — PNG/JPEG ファイルから画像の寸法（幅 × 高さ）を取得します。純粋な Python で実装されており、外部依存関係はありません。スプライト画像のサイズに合わせる衝突オブジェクトのボックス形状を作成するときに使用します。ワークフロー全体については、references/collisionobject.md →「スプライト画像からボックス形状のサイズを設定する」を参照してください。
• scripts/gen_convexshape.py — 2D 画像の透明部分を除いたシルエットから .convexshape ファイルを生成します。PIL/Pillow を使用します。凸包を計算し、16 点以下に単純化して（Box2D の上限）、原点を中心に配置し、Defold の .convexshape 形式で出力します。使用方法については、references/convexshape.md →「画像から生成する」を参照してください。
• scripts/gen_silhouette_chain.py — 画像のシルエット（凹形、穴あり、複数パーツ）をなぞる、回転した TYPE_BOX 形状のチェーンを含む .collisionobject ファイルを生成します。PIL/Pillow を使用します。境界の輪郭ループを抽出し、RDP で単純化して、各辺に沿って細い回転ボックスを配置した .collisionobject を出力します。使用方法については、references/collisionobject.md →「画像の輪郭からシルエットチェーンを生成する」を参照してください。

埋め込みコンポーネントの型名

.go または .collection ファイルにコンポーネントを埋め込む場合、type 文字列には次の値を使用します。

• "sprite" — スプライトコンポーネント
• "label" — ラベルコンポーネント
• "collisionobject" — 衝突オブジェクト
• "sound" — サウンドコンポーネント
• "particlefx" — パーティクルエフェクト
• "model" — 3D モデル
• "mesh" — メッシュ
• "camera" — カメラ
• "factory" — ファクトリー
• "collectionfactory" — コレクションファクトリー
• "collectionproxy" — コレクションプロキシ
• "tilegrid" — タイルマップ（注：型は "tilegrid" であり、"tilemap" ではありません）
• "objectinterpolation" — オブジェクト補間（拡張機能）

GUI コンポーネント（.gui）はインラインで埋め込めません。参照コンポーネントとして追加する必要があります。

Protocol Buffer テキスト形式のルール

これらのルールは、すべての Defold proto テキスト形式ファイルに適用されます。

1. デフォルト値の省略：proto のデフォルト値と同じフィールドは省略します。これにより、ファイルを最小限に保ち、Defold エディターの出力と一致させられます。
2. メッセージブロック：ネストした key: value の組を含む field_name { ... } を使用します。
3. 浮動小数点数：必ず小数点を含めます。1 ではなく 1.0 とします。
4. 整数：小数点は付けません。4.0 ではなく 4 とします。
5. 文字列：必ず二重引用符で囲みます。"text" のようにします。
6. 列挙型：引用符を付けずに定数名を使用します。BLEND_MODE_ALPHA のようにします。
7. ブール値：引用符を付けず、true または false を使用します。
8. 繰り返しフィールド：スカラー値ごとに、フィールド名を付けた行を個別に記述します。
9. 繰り返しメッセージ：各エントリーを個別の field_name { ... } ブロックにします。
10. フィールド順序：proto のフィールド番号順に並べます。
11. 末尾のカンマやセミコロンは付けません。
12. インデント：メッセージブロック内では、ネストのレベルごとに 2 つのスペースを使用します。
13. 改行：メッセージブロック } の終わりと次のフィールドの間には空行を 1 行入れます。連続するスカラーフィールドの間には空行を入れません。
14. 同じネストレベルのフィールドやブロックの間に空行を入れません（Defold エディターの出力に合わせます）。

ベクトル型と数学型の規則

ddf_math.proto の次の型は、多くのファイル形式で使用されます。

dmMath.Vector3 / dmMath.Point3

構成要素：x, y, z（および、まれに使用される d）。すべてのデフォルト値は 0.0 です。

dmMath.Vector3One

構成要素：x, y, z（および、まれに使用される d）。すべてのデフォルト値は 1.0 です。

dmMath.Vector4

構成要素：x, y, z, w。すべてのデフォルト値は 0.0 です。

dmMath.Vector4One

構成要素：x, y, z, w。すべてのデフォルト値は 1.0 です。

dmMath.Vector4WOne

構成要素：x, y, z, w。x/y/z のデフォルト値は 0.0、w のデフォルト値は 1.0 です。

dmMath.Quat

構成要素：x, y, z, w。x/y/z のデフォルト値は 0.0、w のデフォルト値は 1.0 です。

ベクトル／数学ブロックの省略ルール

• デフォルト値と異なる構成要素のみを含めます。
• すべての構成要素がデフォルト値の場合、ブロック全体を省略します（オプションフィールドの場合）。
• フィールドが必須の場合はブロックを含めますが、中身は空にします：position { }

position {
  x: 200.0
  y: 100.0
}
rotation {
  z: 0.7071068
  w: 0.7071068
}

データ文字列のエンコード規則

.collection ファイルに埋め込まれたゲームオブジェクトと、.go ファイルに埋め込まれたコンポーネントは、data フィールド内の複数行文字列として内容をエンコードします。

ネストが1段階（参照コンポーネントを持つゲームオブジェクト）

内容は1回エスケープします。

• 引用符は \" になります
• 改行は \n になります

data: "components {\n"
"  id: \"script\"\n"
"  component: \"/main/main.script\"\n"
"}\n"
""

ネストが2段階（コンポーネントが埋め込まれたゲームオブジェクト）

埋め込まれたコンポーネントの data フィールドは、二重にエスケープする必要があります。

• 外側の引用符：\"
• 内側の引用符（コンポーネントデータ内）：\\\"
• 外側の改行：\n
• 内側の改行（コンポーネントデータ内）：\\n

data: "embedded_components {\n"
"  id: \"camera\"\n"
"  type: \"camera\"\n"
"  data: \"aspect_ratio: 1.0\\n"
"fov: 0.7854\\n"
"near_z: -1.0\\n"
"far_z: 1.0\\n"
"orthographic_projection: 1\\n"
"\"\n"
"}\n"
""

よくある間違い — 内側の data の閉じ引用符：内側の data 文字列を閉じる行（埋め込まれたコンポーネントの data 値を終わらせる \"）では、二重にエスケープした "\"\\n" ではなく、1回だけエスケープした改行 "\"\n" を使用する必要があります。閉じ引用符 \" はネスト階層の境界です。その後は外側（ゲームオブジェクト）の階層に戻るため、改行は1回だけエスケープした \n になります。ここで \\n を使うと、ゲームオブジェクトのデータが破損し、読み込みエラーが発生します。

注：二重にネストされたデータ内の data: \"...\\n" という開始行の後、内側のデータの後続行には先頭の空白がありません（引用文字列の0列目から始まります）。

複数行文字列の連結ブロックは、空の "" 終端子で終了します。1行の data: "" に追加の終端子は不要です。

ワークフロー

新しいファイルの作成

1. ファイルの種類とパスを特定します。
2. references/ 内の該当するリファレンスファイルでフィールド構造を確認します。
3. 必須フィールドをすべて設定します。
4. オプションフィールドは、デフォルト値と異なる場合にのみ設定します。
5. Protobuf Text Format のフィールド番号順に従います。
6. 上記の Protobuf Text Format の規則をすべて適用します。

既存ファイルの編集

1. 現在のファイルを読み取ります。
2. 依頼されたフィールドのみを変更します。
3. 既存のフィールド値と順序を保持します。
4. 省略規則を適用します。編集後にデフォルト値と等しくなるフィールドは削除します。
5. 既存ファイルを編集する場合は、既存の書式スタイルを保持します。