Skip to content

gamedev-skills/awesome-gamedev-agent-skills / skills/other-engines/defold-core

defold-core

Verified

Builds and debugs Defold 1.14 games in Lua: collections, game objects, input focus, msg.post messaging, factories, collection proxies and Bob builds. Use for .collection or .script files, on_input never firing, a proxy that never loads, or "could not be found when dispatching message". Not for LÖVE (`love2d-core`), HUD rules (`game-ui-ux`) or physics feel (`physics-tuning`).

FileKindSize
SKILL.mdskill md14.5 KB
agents/openai.yamlconfig229 B
references/build-and-run.mdmarkdown7.4 KB
references/file-formats.mdmarkdown7.6 KB
scripts/check_defold_project.pyscript29.0 KB

references/file-formats.md

View on GitHub
# Defold file formats (1.14.1)

Every file below comes from one small project that Bob 1.14.1 built (`--variant headless`) and
the 1.14.1 headless engine ran: a player that moves and fires bullets from a factory, a loader
that spawns a wave with a collection factory and loads a level through a collection proxy.
Copy these shapes when you must write editor files by hand; when the editor is available,
let it write them.

## Contents

- [game.project](#gameproject) and [.input_binding](#input_binding)
- [.collection](#collection): instances, embedded instances, nested collections, children,
  proxy-loaded collections
- [.go](#go): file and embedded components, factories, proxies
- [.atlas](#atlas) and [Scripts](#scripts)
- [Where build errors point](#where-build-errors-point): tracing generated-file errors

The editor files are protobuf text format. Fields not shown keep their defaults, `#` starts a
comment, and the field order the editor writes does not matter to Bob. The schemas are the
`*_ddf.proto` files in the Defold engine source.

```text
game.project
input/game.input_binding
main/main.collection      main/player.go   main/player.script
main/main.atlas           main/bullet.go   main/bullet.script
main/loader.go            main/loader.script        main/check.script
main/wave.collection      main/enemy.go
levels/level1.collection  levels/level.script
```

## game.project

INI file, required, in the project root, named exactly `game.project`. Paths name the compiled
file (trailing `c`). Without the `[bootstrap]` key Defold looks for `/logic/main.collectionc`;
without `[input]` it uses `/input/game.input_bindingc`.

```ini
[project]
title = Defold Core Example

[bootstrap]
main_collection = /main/main.collectionc

[input]
game_binding = /input/game.input_bindingc

[physics]
use_fixed_timestep = 1

[engine]
fixed_update_frequency = 60
```

Library dependencies are listed as `dependencies#0 = https://…/archive.zip`, `dependencies#1 =
…`; Bob's `resolve` command fetches them into `.internal/lib/`. Read any setting at run time
with `sys.get_config_string("project.title")`.

## .input_binding

```text
key_trigger {
  input: KEY_LEFT
  action: "left"
}
key_trigger {
  input: KEY_RIGHT
  action: "right"
}
key_trigger {
  input: KEY_SPACE
  action: "fire"
}
mouse_trigger {
  input: MOUSE_BUTTON_LEFT
  action: "touch"
}
```

`/builtins/input/all.input_binding` exists for quick tests; a game should own its bindings.

## .collection

Instances of game object files, an embedded instance, a nested collection and a per-instance
script property override. `name` becomes the socket when the collection is loaded through a
proxy, so every proxied collection needs a unique name.

```text
name: "main"
instances {
  id: "player"
  prototype: "/main/player.go"
  position {
    x: 480.0
    y: 120.0
  }
  component_properties {
    id: "player"                 # id of the script component inside player.go
    properties { id: "speed" value: "250.0" type: PROPERTY_TYPE_NUMBER }
  }
}
instances {
  id: "loader"
  prototype: "/main/loader.go"
}
embedded_instances {
  id: "check"                    # a game object defined inline; here it holds one script
  data: "components {\n  id: \"check\"\n  component: \"/main/check.script\"\n}\n"
}
collection_instances {
  id: "decor"
  collection: "/main/wave.collection"
  position {
    x: 100.0
    y: 400.0
  }
}
scale_along_z: 0
```

Ids inside a nested collection are prefixed with its id: the `leader` object in `decor` is
`/decor/leader`. A child is attached with `children: "child_id"` on the parent instance:

```text
name: "wave"
instances {
  id: "leader"
  prototype: "/main/enemy.go"
  children: "wingman"
}
instances {
  id: "wingman"
  prototype: "/main/enemy.go"
  position {
    x: 64.0
  }
}
scale_along_z: 0
```

A collection that only holds embedded instances, as loaded by a proxy:

```text
name: "level1"
embedded_instances {
  id: "level"
  data: "components {\n"
  "  id: \"level\"\n"
  "  component: \"/levels/level.script\"\n"
  "}\n"
  ""
}
scale_along_z: 0
```

## .go

`components` reference component files (a script here); `embedded_components` carry the
component's own file as an escaped string, split across adjacent quoted lines.

```text
components {
  id: "player"
  component: "/main/player.script"
}
embedded_components {
  id: "sprite"
  type: "sprite"
  data: "default_animation: \"blob\"\n"
  "material: \"/builtins/materials/sprite.material\"\n"
  "textures {\n"
  "  sampler: \"texture_sampler\"\n"
  "  texture: \"/main/main.atlas\"\n"
  "}\n"
  ""
}
embedded_components {
  id: "bulletfactory"
  type: "factory"
  data: "prototype: \"/main/bullet.go\"\n"
  ""
}
```

The loader object holds the other two spawning components:

```text
components {
  id: "loader"
  component: "/main/loader.script"
}
embedded_components {
  id: "levelproxy"
  type: "collectionproxy"
  data: "collection: \"/levels/level1.collection\"\n"
  ""
}
embedded_components {
  id: "wavefactory"
  type: "collectionfactory"
  data: "prototype: \"/main/wave.collection\"\n"
  ""
}
```

Older sprite data uses `tile_set: "/main/main.atlas"` instead of the `textures` block; keep
whichever form the project already uses.

## .atlas

```text
images {
  image: "/builtins/graphics/particle_blob.png"
}
animations {
  id: "blob"
  images {
    image: "/builtins/graphics/particle_blob.png"
  }
  playback: PLAYBACK_LOOP_FORWARD
  fps: 8
}
```

A sprite's `default_animation` names an image (file name without extension) or an animation
id in its atlas.

## Scripts

`bullet.script`, spawned by the player's factory with a `velocity` override:

```lua
go.property("velocity", vmath.vector3(0, 400, 0))
go.property("lifetime", 1.5)

function update(self, dt)
	go.set_position(go.get_position() + self.velocity * dt)
	self.lifetime = self.lifetime - dt
	if self.lifetime <= 0 then
		go.delete()                         -- deletes this game object at the end of the frame
	end
end
```

`level.script`, inside the proxy-loaded world, reporting back to the main world:

```lua
local LEVEL_DONE = hash("level_done")

function init(self)
	self.time = 0
	print("level init", msg.url())          -- url: [level1:/level#level]
end

function update(self, dt)
	self.time = self.time + dt
	if self.time >= 0.5 and not self.reported then
		self.reported = true
		msg.post("main:/loader#loader", LEVEL_DONE, { seconds = self.time })
	end
end
```

Shared code goes in `.lua` modules, loaded with a dotted path from the project root:
`local util = require "modules.util"` loads `/modules/util.lua`.

The run printed, in order: `wave leader hash: [/collection0/leader]`,
`level init url: [level1:/level#level]`, `level done after 0.5…`, `level unloaded`.

## Where build errors point

Bob names the source file and line 0 for most reference errors:

```text
ERROR: game.project:0: '…the bootstrap.main_collection '/main/main.collectio' can't be found'
ERROR: main/probe.script:0: '…the Lua module '/modules/nothere.lua' can't be found'
ERROR main/main.atlas:0 Resource 'main/images/missing.png' is not created
```

For an embedded component, Bob reports a generated file instead of the `.go` that holds it:

```text
ERROR: build/default/_generated_c1d664c47a440ab4.factory:0: '…the prototype '/main/missing.go' can't be found'
```

The generated name does not exist in the sources. Search them for the quoted path in the
message (`"/main/missing.go"`, written as `\"/main/missing.go\"` inside embedded data) or run
`scripts/check_defold_project.py`, which reports the `.go` file and line.

A missing resource property (`go.property("art", resource.atlas("/main/nope.atlas"))`) appears
only in the `SEVERE` stack trace lines: `Resource '/main/nope.atlas' referenced from script
resource property 'art' does not exist`.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 323kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall