Defold has four Lua script types (each running in a different context with different APIs) and plain .lua modules for reusable logic.
For API details use defold-api-fetch skill. For conceptual manuals use defold-docs-fetch skill. This skill covers script structure, constraints, and templates.
Lua modules (.lua)
Plain .lua files are Lua modules used to encapsulate reusable logic. Extract frequently used universal logic into .lua modules — avoid duplication and keep scripts lean. Modules are required via require("path.to.module") (dots as path separators).
Defold projects typically use Lua shared state (shared_state in game.project). When enabled, all scripts, GUI scripts, and the render script run in the same Lua context. A Lua module required from any script has the same context and state within that single Lua interpreter instance — module-level locals and package.loaded are shared across all users of the module. Stateful modules behave like singletons.
Lua module structure (.lua)
Encapsulate data and functions in a local table, return it:
local M = {}
function M.hello() print("Hello") end
return M
Avoid globals in modules. For stateful modules, internal state is shared between all callers (singleton-like). For stateless logic, pass state explicitly or use constructors that return new state tables. See [Modules manual](https://defold.com/llms/manuals/modules.md).
## Script types
| Extension | Context | Lua runtime | `go.property()` | Key namespaces |
|---|---|---|---|---|
| `.script` | Game object component | LuaJIT | Yes | `go`, `msg`, `vmath`, `timer`, `sys`, component namespaces (`sprite`, `label`, `factory`, `collectionfactory`, `collectionproxy`, `tilemap`, `model`, `sound`, `particlefx`, `buffer`, `resource`, `physics`) |
| `.gui_script` | GUI component | LuaJIT | No | `gui`, `msg`, `vmath`, `sys` |
| `.render_script` | Render pipeline (one per project) | LuaJIT | No | `render`, `graphics`, `camera`, `msg`, `vmath`, `sys` |
| `.editor_script` | Defold editor | Lua 5.2 (luaj) | No | `editor`, `editor.ui`, `editor.prefs`, `editor.tx`, `http`, `json`, `zip`, `zlib` |
## File format
All script types and `.lua` modules are plain Lua files (not Protobuf Text Format). Scripts use specific extensions (`.script`, `.gui_script`, etc.); modules use `.lua`.
## Runtime environment notes (.script, .gui_script, .render_script)
**Platform-specific**: `html5` module is only available on the **HTML5** platform.
**App Manifest exclusions**: Some built-in modules (`liveupdate`, `image`, `types`, `profiler`, `sound`, `physics`, etc.) can be excluded via the App Manifest to reduce binary size. If excluded, their APIs will not be available at runtime.
**No `utf8` module**: For working with non-ASCII strings, use the defold-utf8 dependency (`https://github.com/d954mas/defold-utf8/archive/refs/heads/master.zip`). API reference: [utf8.script_api](https://github.com/d954mas/defold-utf8/blob/master/utf8/api/utf8.script_api).
## Common runtime script patterns (.script, .gui_script, .render_script)
All runtime lifecycle callbacks receive `self` as the first parameter — a userdata that acts like a table for storing instance state.
### Script structure
1. **Module requires** (optional) — `local M = require("module")`
2. **Local helper functions** (optional) — must be at module scope, never inside other functions
3. **Declarations** (`.script` only: `go.property()` at top level)
4. **Lifecycle callbacks**
### Lifecycle callback availability
| Callback | `.script` | `.gui_script` | `.render_script` |
|---|---|---|---|
| `init(self)` | ✓ | ✓ | ✓ |
| `final(self)` | ✓ | ✓ | — |
| `fixed_update(self, dt)` | ✓ | — | — |
| `update(self, dt)` / `update(self)` | ✓ (dt) | ✓ (dt) | ✓ (no dt) |
| `late_update(self, dt)` | ✓ | — | — |
| `on_message(self, message_id, message, sender)` | ✓ | ✓ | ✓ (no sender) |
| `on_input(self, action_id, action)` | ✓ | ✓ | — |
| `on_reload(self)` | ✓ | ✓ | — |
### Key rules
- Store per-instance state in `self`, not in module-level locals (module-level locals are shared across all instances).
- Omit unused callbacks — especially `update()` and `fixed_update()` which cost a call per frame even if empty.
- Keep local helper functions at module scope, never inside other functions.
## Native extensions
Native extensions (C/C++/ObjC/Java) register their Lua functions into the global scope via the Lua C API (`lua_register`, `luaL_openlib`, etc.). This means extensions typically add a new global table (e.g., `myext`) with functions and constants accessible from any `.script` or `.gui_script`.
Extensions describe their API for editor auto-complete via `*.script_api` files (YAML format) located in their `api/` directory. The format:
```yaml
- name: extension_name
type: table
desc: Extension description
members:
- name: function_name
type: function
desc: Function description
parameters:
- name: param_name
type: string
desc: Parameter description
returns:
- name: return_name
type: number
desc: Return value description
Types: table, string, boolean, number, function. Multiple types: [type1, type2].
Lua preprocessing
Defold supports conditional compilation via the Lua preprocessor extension (applies to all Lua files including .lua modules):
--#IF DEBUG
local lives = 999
--#ELSE
local lives = 3
--#ENDIF
Keywords: RELEASE, DEBUG, HEADLESS.
Type-specific references
Consult the references/ directory for constraints, templates, and patterns specific to each script type:
references/script.md—go.property()reference (types, constraints, overrides), templatesreferences/gui_script.md— GUI script constraints, template node access, templatesreferences/render_script.md— render pipeline architecture, system messages, full working templatesreferences/editor_script.md— module structure, commands, lifecycle hooks, execution modes, templates
Workflow
Creating a new Lua module (.lua)
- Use when logic is reusable across multiple scripts or screens.
- Create a local table, add functions, return it.
- Keep modules stateless when possible; if stateful, document that state is shared.
- Require with dot notation:
require("main.utils"),require("screens.game.helpers").
Creating a new script
- Determine the correct extension for the script type.
- Read the corresponding type-specific reference in
references/for constraints and templates. - Follow the structure pattern: requires → helpers → declarations → callbacks.
- Only add lifecycle callbacks you actually need.
Editing an existing script
- Read the current file.
- Preserve existing declarations (e.g.,
go.property()names) and callback signatures. - Add/modify callbacks as needed.
- Changing a
go.property()name or type may break overrides in.goand.collectionfiles.