defold-proto-file-editing

编辑 Defold Proto 文本格式文件

创建和编辑使用 Protobuf 文本格式的 Defold 资源和组件文件。

适用场景

此技能涵盖所有以 Protobuf 文本格式序列化的 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 部分中声明，即可使用两个特殊顶点属性：

• 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 — 根据二维图像的非透明轮廓生成 .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）不能以内联方式嵌入 — 必须作为引用组件添加。

Protobuf 文本格式规则

这些规则适用于所有 Defold proto 文本格式文件：

1. 省略默认值：省略等于其 proto 默认值的字段。这样可以保持文件精简，并与 Defold 编辑器的输出一致。
2. 消息块：使用 field_name { ... }，其中包含嵌套的 key: value 对。
3. 浮点数：始终包含小数点：1.0，而不是 1。
4. 整数：不包含小数点：4，而不是 4.0。
5. 字符串：始终使用双引号："text"。
6. 枚举：使用不带引号的常量名称：BLEND_MODE_ALPHA。
7. 布尔值：使用 true 或 false，不加引号。
8. 重复字段：每个标量值都使用字段名称单独占一行。
9. 重复消息：每个条目都使用独立的 field_name { ... } 块。
10. 字段顺序：遵循 proto 字段编号顺序。
11. 不使用尾随逗号或分号。
12. 缩进：消息块内每个嵌套层级缩进 2 个空格。
13. 换行：消息块 } 结束后与下一个字段之间空一行。连续的标量字段之间不留空行。
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 字段中的多行字符串。

单层嵌套（带有引用组件的游戏对象）

内容转义一次：

• 引号变为 \"
• 换行符变为 \n

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

双层嵌套（带有嵌入组件的游戏对象）

嵌入组件的 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 字符串的那一行（终止嵌入组件数据值的 \"）必须使用单次转义的换行符 "\"\n"，而不是双重转义的 "\"\\n"。结束引号 \" 是嵌套层级之间的边界——此后回到外层（游戏对象）层级，因此换行符应为单次转义的 \n。在这里使用 \\n 会损坏游戏对象数据并导致加载错误。

注意：在双层嵌套数据中，data: \"...\\n" 这一行的开头之后，内层数据的后续行前面不带空格（它们从带引号字符串的第 0 列开始）。

多行字符串拼接块以一个空的 "" 终止符结尾。单行 data: "" 无需额外的终止符。

工作流

创建新文件

1. 确定文件类型和路径。
2. 查阅 references/ 中相关的参考文件，了解字段结构。
3. 设置所有必需字段。
4. 仅当可选字段与默认值不同时才设置。
5. 按 proto 字段编号顺序排列。
6. 遵循上述所有 Protobuf Text Format 规则。

编辑现有文件

1. 读取当前文件。
2. 仅修改请求的字段。
3. 保留现有字段值和顺序。
4. 应用省略规则：编辑后与默认值相同的字段应移除。
5. 编辑现有文件时，保留其现有格式风格。