Home › Defold › Defold game engine AGENTS.md

Defold game engine AGENTS.md

AGENTS.md for Defold games in Lua: game objects and components, message passing, script lifecycle, and native extensions.

AGENTS.mdDefold

Copy AGENTS.md

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

# AGENTS.md: Defold game

## Commands
- Build/run from the editor (Project > Build), or headless with bob: `java -jar bob.jar --variant debug resolve build`
- Lint Lua with `luacheck` if configured.
- Check `game.project` for the Defold version before using new APIs.

## Architecture
- Logic lives in `.script` (game object), `.gui_script` (GUI), and `.render_script` files, plus shared Lua modules (`require "modules.inventory"`).
- Collections compose game objects; spawn dynamic objects with factories (`factory.create("#enemy_factory", pos)`) and collection factories for groups.
- Communicate with message passing: `msg.post("/player#script", "take_damage", { amount = 10 })`, handled in `on_message` by comparing `message_id == hash("take_damage")`. Pre-hash ids at module top (`local TAKE_DAMAGE = hash("take_damage")`).
- Per-instance state lives in `self`; module-level variables are shared by every instance, so use them only for constants.
- Lifecycle: `init`, `update(self, dt)`, `fixed_update` for physics, `on_input`, `final`. Acquire input focus with `msg.post(".", "acquire_input_focus")` and release it in `final`.
- Animate with `go.animate` / `gui.animate` instead of manual tweens in `update`.
- Use `go.property` for tweakable values set in the editor.

## Don't
- Don't edit `.collection`/`.go` text files by hand beyond trivial property changes; describe editor steps instead.
- Don't poll every frame for things messages or callbacks can signal.

## Done
The project builds with bob without errors, and the changed behavior works in a debug build.