Guides
Learn defold-typescript in order — core concepts first, sharp edges last.
Tutorial
Build a complete game to see the whole workflow end to end.
TypeScript
Writing TypeScript for this toolchain and how it lowers to Lua.
- TypeScript vs LuaA translation cheat sheet for Defold developers who already know Lua.
- TypeScript gotchasSharp edges where TypeScript, the TypeScriptToLua transpiler, or the Defold runtime behave in ways the type system cannot fully express.
- Data structuresTypeScript ships a richer set of containers than Lua's single
table, and the toolchain lowers each one to code Defold's Lua 5.1 VM runs.
Core concepts
How Defold's script model works in TypeScript.
- Script lifecycle
@defold-typescript/typesexports identity helpers for Defold script tables. - MessagesDefold delivers a message as a hashed id and a plain table, so the payload's shape is invisible to TypeScript by default.
- Script stateA Defold game is many script instances sharing a few script modules.
- Vector mathDefold exposes vector arithmetic through Lua metamethods on
vector3,vector4,quaternion, andmatrix4.
CLI
The command-line verbs you run day to day.
- init
initscaffolds a Defold project with a TypeScript surface — or adds TypeScript to an existing Defold project. - watch
watchrebuilds your Lua incrementally on every TypeScript change. - build
buildtranspiles every TypeScript file undersrc/to Lua and writes the result into the Defold project tree — a one-shot compile. - wallThis page covers
wall, the opt-in command for narrowing the API surface of a source directory to a single script kind. - resolve
resolvereads the Defold dependencies declared in yourgame.project, fetches each archive, and generates the TypeScript types for them — so extension…
Toolchain & workflow
Build, inspect, and drive the transpiler.
- Transpile diagnostics
bunx @defold-typescript/cli@latest init .scaffolds a TypeScript language-service plugin,@defold-typescript/tstl-plugin, into the generated… - DebuggingStep through your TypeScript with breakpoints set directly in the
.tssource, even though Defold runs the transpiled Lua. - Agent runbooksHarness-neutral procedures for driving
defold-typescriptfrom an automated agent. - Helper scriptsBuild tools, codegen, and one-off maintenance scripts belong outside your Defold source tree, in a project-root
/scriptsfolder, and run with Bun.
Project configuration
Pin the engine and add native code.
Migration
Comparing surfaces and moving off ts-defold.