Guides
Learn defold-typescript in order — core concepts first, sharp edges last.
Tutorials
Build complete games and learn the ideas behind them.
Build Tetris
This tutorial walks you through building a complete game in Defold with TypeScript: writing .ts,…
Vectors & rotations
Watch a spaceship glide across a Defold game.
Learn state machines
A hands-on introduction to hsm (Hierarchical State Machine), the library for Defold and TypeScript that ships with this toolchain.
Learn entity systems
A hands-on introduction to ecs, the entity system library that ships with this toolchain.
TypeScript
Writing TypeScript for this toolchain and how it lowers to Lua.
TypeScript vs Lua
A translation cheat sheet for Defold developers who already know Lua.
TypeScript gotchas
Sharp edges where TypeScript, the TypeScriptToLua transpiler, or the Defold runtime behave in ways the type system cannot fully express.
Data structures
TypeScript 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.
Lua table constructs
Defold's reference is written in Lua, and several engine calls take a table whose keys are engine constants.
Core concepts
How Defold's script model works in TypeScript.
Script lifecycle
@defold-typescript/types exports identity helpers for Defold script tables.
Messages
Defold delivers a message as a hashed id and a plain table, so the payload's shape is invisible to TypeScript by default.
Script state
A Defold game is many script instances sharing a few script modules.
Vector math
Defold exposes vector arithmetic through Lua metamethods on vector3, vector4, quaternion, and matrix4.
Editor scripts
An editor script extends the Defold editor itself — custom menu commands, save and bundle hooks, language servers — rather than the running game.
State machines
hsm is a small typed hierarchical state machine library that ships with the toolchain and compiles to plain Lua.
Entity systems
ecs is a small typed entity system library that ships with the toolchain and compiles to plain Lua.
ecs and hsm together
A state machine decides what one object is doing; an entity system does the same work for many objects every frame.
CLI
The command-line verbs you run day to day.
init
init scaffolds a Defold project with a TypeScript surface — or adds TypeScript to an existing Defold project.
init-agents
init-agents writes the agent contract at the project root: AGENTS.md, which tells any AI harness (or human) opening the repo how this project is built and…
upgrade
upgrade is the verb that moves a project to the latest toolchain.
set-target
set-target writes the project's Defold API target — the defold-target pin in package.json — to a fixed version, a release channel, or the version of the…
watch
watch rebuilds your Lua incrementally on every TypeScript change.
reload
reload pushes one reload into the game running under the Defold editor, then reads that editor's console for a…
build
build transpiles every TypeScript file under src/[^src-root] to Lua and writes the result into the Defold project tree — a one-shot compile.
run
run launches a project you already compiled — the Runnable (an engine executable plus a build/default/game.projectc) left in the tree by a prior build…
bob
bob is Defold's own headless build tool — the bob.jar the editor uses under the hood.
wall
This page covers wall, the opt-in command for narrowing the API surface of a source directory to a single script kind.
resolve
resolve reads the Defold dependencies declared in your game.project, fetches each archive, and generates the TypeScript types for them — so extension…
scene-types
scene-types reads the .collection and .go files in your project and writes one declaration file naming every game-object path and component id they…
view
view opens a file's state machines and entity worlds in your browser and runs them there, when checks, run…
library
library works on library data: the per-library folders resolve prints its library declarations from.
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…
Debugging
Set a breakpoint in a .ts file, press F5, and step through your own source while Defold runs the transpiled Lua.
Agent runbooks
Harness-neutral procedures for driving defold-typescript from an automated agent.
Helper scripts
Build tools, codegen, and one-off maintenance scripts belong outside your Defold source tree, in a project-root /scripts folder, and run with Bun.
Test with Bun
Game logic written in TypeScript can be unit-tested with bun test, with no Defold engine running.
Terminal output
The CLI's headline lines start with defold-typescript <command>: , whether they report a failure, a warning, or ordinary progress, and they share stderr.
Project configuration
Pin the engine and add native code.
Pinning the Defold target
@defold-typescript/types ships the latest/current Defold API surface pre-baked, along with a small retained set of recent releases; every other…
Upgrading the toolchain
One command moves a project to the latest toolchain:
Upgrading Defold versions
This is the standing runbook for moving a project from one pinned Defold API surface to another, followed by one section per release recording exactly what…
Native extensions
Defold native extensions ship their own Lua API alongside the engine's.
Shipping types with a library
A Defold library can ship its own TypeScript declarations.
Migration
Comparing surfaces and moving off ts-defold.
API docs vs ts-defold-types
How the JSDoc that @defold-typescript/types emits compares with the incumbent hand-and-script-maintained…
Migrating from ts-defold
Moving a Defold + TypeScript project from the ts-defold stack (@ts-defold/types, @ts-defold/create) to…
Releases
What changed in each published toolchain version.