Defold Proto File Editing

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.

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.

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.