Editing Defold Proto Text Format Files

Creates and edits Defold resource and component files that use Protobuf Text Format.

When to use

This skill covers all Defold file types that are serialized as Protobuf Text Format. It does NOT cover Lua script files (.script, .gui_script, .render_script, .editor_script).

Supported file types

For detailed field references, consult the per-type reference file in references/:

• references/collection.md — .collection files (game levels, hierarchies)
• references/gameobject.md — .go files (game object prototypes)
• references/gui.md — .gui files (GUI scenes)
• references/atlas.md — .atlas files (texture atlases)
• references/sprite.md — .sprite files (sprite components)
• references/collisionobject.md — .collisionobject files (physics)
• references/convexshape.md — .convexshape files (external convex hull collision shapes)
• references/label.md — .label files (text in game space)
• references/font.md — .font files (font resources)
• references/material.md — .material files (render materials)
• references/model.md — .model files (3D models)
• references/mesh.md — .mesh files (custom 3D meshes from buffer data)
• references/particlefx.md — .particlefx files (particle effects)
• references/sound.md — .sound files (audio)
• references/camera.md — .camera files (camera components)
• references/factory.md — .factory files (object spawning)
• references/collectionfactory.md — .collectionfactory files (collection spawning)
• references/collectionproxy.md — .collectionproxy files (world loading)
• references/tilemap.md — .tilemap files (tile grids)
• references/tilesource.md — .tilesource files (tile source resources)
• references/objectinterpolation.md — .objectinterpolation files (extension: interpolation of fixed step movement)

For skill maintenance tasks (updating references, fetching proto schemas), use the defold-skill-maintain skill.

Shaders and materials relationship

Shaders (.vp, .fp, .glsl) are GLSL files and are NOT covered by this skill — use the defold-shaders-editing skill for shader files. However, shaders and materials are tightly coupled:

Data flow from material to shader

1. Constants declared in vertex_constants / fragment_constants become uniform variables in shaders. Engine-provided constants (CONSTANT_TYPE_VIEW, CONSTANT_TYPE_PROJECTION, etc.) are automatically populated. User constants (CONSTANT_TYPE_USER) can be animated via go.set() / go.animate().

2. Samplers declared in samplers become sampler2D uniforms. The sampler name in the material must match the uniform name in the shader.

3. Attributes declared in attributes become vertex in variables. Semantic types like SEMANTIC_TYPE_POSITION, SEMANTIC_TYPE_TEXCOORD provide engine-generated data.

Instancing with mtx_world and mtx_normal

For instanced rendering, two special vertex attributes are available without declaring them in the material's attributes section:

• mtx_world — mat4 world transformation matrix (per-instance)
• mtx_normal — mat4 normal transformation matrix (per-instance)

When these are declared as vertex in attributes in the shader, Defold automatically enables instanced rendering:

// 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;
}

Requirements for instancing:

• Material must have vertex_space: VERTEX_SPACE_LOCAL
• Shader declares mtx_world and/or mtx_normal as in attributes
• No need to add these to the material's attributes list

Reference examples

Built-in shader examples are in .deps/builtins/materials/:

• sprite.vp / sprite.fp — 2D sprite rendering (world space)
• model.vp / model.fp — 3D model rendering (local space, uniforms)
• model_instanced.vp — 3D model with instancing (uses mtx_world, mtx_normal as attributes)

Bundled scripts

• scripts/get_image_size.py — Get image dimensions (width × height) from PNG/JPEG files. Pure Python, no external dependencies. Use this when creating collision object box shapes that should match sprite image sizes. See references/collisionobject.md → "Sizing box shapes from sprite images" for the full workflow.
• scripts/gen_convexshape.py — Generate a .convexshape file from a 2D image's non-transparent silhouette. Uses PIL/Pillow. Computes a convex hull, simplifies to ≤16 points (Box2D limit), centers at origin, and outputs Defold .convexshape format. See references/convexshape.md → "Generating from an image" for usage.
• scripts/gen_silhouette_chain.py — Generate a .collisionobject file with a chain of rotated TYPE_BOX shapes tracing the contour of any image silhouette (concave, with holes, multi-part). Uses PIL/Pillow. Extracts boundary contour loops, simplifies with RDP, and outputs a .collisionobject with thin rotated boxes along each edge. See references/collisionobject.md → "Silhouette chain from image contour" for usage.

Embedded component type names

When embedding components in .go or .collection files, these are the type string values:

• "sprite" — Sprite component
• "label" — Label component
• "collisionobject" — Collision object
• "sound" — Sound component
• "particlefx" — Particle effect
• "model" — 3D model
• "mesh" — Mesh
• "camera" — Camera
• "factory" — Factory
• "collectionfactory" — Collection factory
• "collectionproxy" — Collection proxy
• "tilegrid" — Tilemap (note: type is "tilegrid", not "tilemap")
• "objectinterpolation" — Object interpolation (extension)

GUI components (.gui) CANNOT be embedded inline — they must be added as referenced components.

Protobuf Text Format rules

These rules apply to ALL Defold proto text format files:

1. Default omission: Omit fields that equal their proto default. This keeps files minimal and matches Defold editor output.
2. Message blocks: Use field_name { ... } with nested key: value pairs.
3. Floats: Always include decimal point: 1.0, not 1.
4. Integers: No decimal point: 4, not 4.0.
5. Strings: Always double-quoted: "text".
6. Enums: Use the constant name without quotes: BLEND_MODE_ALPHA.
7. Booleans: true or false, no quotes.
8. Repeated fields: Each scalar value gets its own line with the field name.
9. Repeated messages: Each entry gets its own field_name { ... } block.
10. Field order: Follow the proto field number order.
11. No trailing commas or semicolons.
12. Indentation: 2 spaces per nesting level inside message blocks.
13. Newlines: One empty line between the end of a message block } and the next field. No empty line between consecutive scalar fields.
14. No blank lines between fields or blocks within the same nesting level (match Defold editor output).

Vector and math type conventions

These types from ddf_math.proto appear across many file types:

dmMath.Vector3 / dmMath.Point3

Components: x, y, z (and d, rarely used). All default to 0.0.

dmMath.Vector3One

Components: x, y, z (and d, rarely used). All default to 1.0.

dmMath.Vector4

Components: x, y, z, w. All default to 0.0.

dmMath.Vector4One

Components: x, y, z, w. All default to 1.0.

dmMath.Vector4WOne

Components: x, y, z, w. x/y/z default to 0.0, w defaults to 1.0.

dmMath.Quat

Components: x, y, z, w. x/y/z default to 0.0, w defaults to 1.0.

Omission rules for vector/math blocks

• Only include components that differ from their default value.
• If all components are at defaults, omit the entire block (for optional fields).
• If the field is required, include the block but leave it empty: position { }.

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

Data string encoding rules

Game objects embedded in .collection files and components embedded in .go files encode their content as multi-line strings in a data field.

Single nesting level (game object with referenced components)

The content is escaped once:

• Quotes become \"
• Newlines become \n

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

Double nesting level (game object with embedded components)

The embedded component's data field requires double escaping:

• Outer quotes: \"
• Inner quotes (inside component data): \\\"
• Outer newlines: \n
• Inner newlines (inside component data): \\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"
""

Common mistake — closing quote of inner data: The line that closes the inner data string (the \" that ends the embedded component's data value) must use single-escaped newline "\"\n", NOT double-escaped "\"\\n". The closing quote \" is the boundary between nesting levels — after it, you are back at the outer (game object) level, so the newline is single \n. Using \\n here corrupts the game object data and causes a load error.

Note: After the opening data: \"...\\n" line inside double-nested data, subsequent lines of that inner data do NOT have leading whitespace (they start at column 0 of the quoted string).

Multi-line string concatenation blocks end with an empty "" terminator. A single-line data: "" does not need an additional terminator.

Workflow

Creating a new file

1. Determine the file type and path.
2. Consult the relevant reference file in references/ for the field structure.
3. Set all required fields.
4. Set optional fields only if they differ from defaults.
5. Follow proto field number order.
6. Apply all Protobuf Text Format rules above.

Editing an existing file

1. Read the current file.
2. Modify only the requested fields.
3. Preserve existing field values and order.
4. Apply omission rules: remove fields that become equal to their defaults after editing.
5. When editing existing files, preserve the existing formatting style.