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.