Skip to Content
defold-typescript
Get startedGuidesAPILibraries
CLI

Watch

watch rebuilds your Lua incrementally on every TypeScript change. Run it in the editor's integrated terminal and leave it running while you work; the Defold editor picks up each rebuild.

bunx @defold-typescript/cli watch

Tip

watch keeps two derived surfaces current while it runs: it re-runs resolve on a game.project save or a Defold library fetch, and regenerates the scene-address declaration on a .go, .collection, .collectionproxy or .collectionfactory save — and on a game.project save too, once that resolve has settled. Only the scene declaration is bootstrapped at startup — run resolve once before watch.

What it does

watch holds one long-lived transpile session and re-reads and rewrites only the files you actually edit, skipping the re-glob and re-read of unchanged sources, so a rebuild after a save is near-instant. Each source under src/1 becomes exactly one output, the same mapping build uses: a lifecycle-factory file becomes a Defold component (src/main.ts -> src/main.ts.script), a plain module becomes a Lua module (src/util.ts -> src/util.lua). Adding or removing a factory switches the artifact kind, and watch prunes the stale alternative so a kind switch never leaves the old output behind.

Keep Defold open on the same project folder you run watch in, and run the game from the editor after a rebuild completes.

Keeping the extension surface current

watch re-runs resolve whenever you save game.project, re-materializing .defold-types/extensions/ from the declared [dependencies]. It also re-runs it when the Defold editor fetches libraries (Project -> Fetch Libraries, which rewrites .internal/lib/dependencies.json), so the types follow the archives the game now builds with. It does not bootstrap that surface: run resolve once before watch so the initial extension types exist; watch only reconciles later changes.

Keeping the scene addresses current

watch regenerates the scene-address declaration after its initial build, and again on every save to an input that regeneration re-reads: a .go or .collection, a standalone .collectionproxy or .collectionfactory, and game.project. Unlike the extension surface this needs no bootstrap run — that startup pass writes it.

The reference documents are there because they are what says which world a collection is, and the two say different things. A .collectionproxy opens a collection as its own socket, so retargeting one moves the addresses the declaration offers — the old socket's keys go, the new socket's arrive. A .collectionfactory marks a collection as a prototype with no static path of its own, so pointing one at a collection neither adds nor removes a key: it closes that collection's reached by no bootstrap, proxy, instance or factory reference warning, and removing the reference reopens it. game.project is there for [bootstrap] main_collection, which decides whose paths are bare. A game.project save runs one regeneration, after the resolve above has settled, so the walk reads the dependencies that resolve just materialized.

Each of those saves also re-checks the project's #fragment addresses against the refreshed universe, so a component you remove is reported before you touch any TypeScript. The startup regeneration is the exception and reports nothing.

Runtime errors in the terminal

While a Defold editor is open on this project, watch reads its console and prints the ERROR: and WARNING: lines — with their stack tracebacks — into the same terminal you are already watching. That covers the failures the transpiler cannot see: code that compiles clean and then throws in the running game. It needs no flag, because --hot-reload governs whether a reload is posted, not whether the editor is read. Where the build's source map can answer, each reported location names the authored .ts line in front of the generated chunk one; see reload for when that mapping is available. The same holds for an editor opened at any time after watch started: watch checks for one about once a second, so it is picked up with no save needed. On a terminal the leading ERROR and WARNING tags are colored; see Terminal output.

An editor that attaches after startup is also asked its version, because the startup pin check may have found no editor to compare against. If it disagrees with a concrete defold-target pin, watch prints the same set-target --detected notice startup would have; with no pin, it names both versions and tells you to restart watch, since the API surface stays fixed for the life of the loop. A version that matches the target, the version startup already compared, or the last version reported is not reported again; an editor that goes from 1.13.0 to 1.14.0 and back to 1.13.0 is reported three times unless startup compared 1.13.0. A check that is still running when its editor quits, or is replaced by another editor, reports nothing. A channel pin or a --defold-target override is never checked, and the notice never changes the exit status, even under --fail-on-drift.

Ordinary INFO:/DEBUG: frame logging is filtered out, and console history recorded before watch attached is skipped — attaching mid-session prints the next error rather than replaying old ones. Under --json these lines stay on stderr and never enter the event stream on stdout.

The console does not carry Defold's own build errors, such as a bad component reference, a missing atlas or a Lua syntax error; those come from compiling the project. To see them in the terminal as well, run with --editor-compile.

Hot reload

--hot-reload pushes each successful rebuild that changes a file into the game running under the Defold editor, so you stop pressing Build after every edit. A rebuild whose outputs already hold the same bytes, such as a re-save with no edit, posts no reload:

bunx @defold-typescript/cli watch --hot-reload

Four things are worth knowing about how it behaves:

  • A failed build reloads nothing, and stops nothing. A compile error — a type error, an unreachable require, an unsplittable script, a contested output path — is printed and the loop keeps watching, so fixing the file rebuilds it; only a setup failure such as an unreadable tsconfig.json ends the run. The running game stays on the last code that actually built, rather than being pushed the previous emit's Lua and making the change look like it did nothing. The outputs a failed rebuild did write, for its sources without errors, are reloaded with the next successful rebuild, even one that writes nothing new.
  • The editor may come and go. The port is re-read on every reload, and while no editor is attached watch looks for one about once a second, so an editor opened at any time after the loop started is attached without a save. One that quits is reported once and leaves the loop rebuilding until it returns. A console connection that drops while the editor keeps running, as after the machine sleeps, is reopened without announcing the editor again. A reload that lands on a different editor while the old one's console is still open attaches the new editor, and the old console closing later leaves it attached and starts reading its console instead. An editor whose console fails to open is retried at growing intervals, up to about 30 seconds apart, so its runtime errors appear once the console opens and an editor that quits meanwhile is still reported. Nothing more is printed while the game is not running — that is the ordinary case, not an error.
  • Editor scripts reload separately. An emit that touched a .ts.editor_script reloads the editor's extensions instead; an emit touching both kinds does both.
  • A refused reload says so. If the editor is found but the reload does not land, the terminal names that editor's address once and stops reporting it as attached, rather than leaving you watching a loop that believes it is connected. The attach line returns when a reload succeeds again.
  • A rejected reload shows its issues. Defold 1.13.2 and later answer a reload once it has finished and say whether it succeeded. A rejected reload prints each issue as <resource>:<line>: <severity>: <message> and keeps the editor attached, since it answered. Older editors only queue the reload, so their errors reach the terminal through the console alone.

Hot reload runs the new code against the old state and does not re-run init. See Script lifecycle for what belongs in on_reload.

Compile in the editor

--editor-compile asks the open Defold 1.13.2+ editor to compile the project, without running it, after every successful rebuild and every change to a project file such as a .collection, .atlas or hand-written .lua:

bunx @defold-typescript/cli watch --editor-compile

Each issue the editor reports is printed the way build --editor-compile prints it, with generated-script locations pointing at the TypeScript line:

defold-typescript watch: editor: src/player.ts:12:5 (/src/player.ts.script:40): error: attempt to call a nil value

How it behaves:

  • A failed compile never ends the loop. It prints the issues and an error line, and the exit status stays 0. Once the project compiles cleanly again, one line says so.
  • Only real project changes compile. The Lua watch writes itself, build/, .internal/, .git/, anything under node_modules or .defold-types, and any path your .defignore lists are skipped. Edits to .defignore apply straight away. A build that fails to transpile compiles nothing, so the editor never judges stale Lua.
  • One compile at a time. Changes that land while a compile runs are folded into one more compile after it finishes.
  • No editor is not an error. No editor, an editor older than 1.13.2, or a refused request prints one line, and the line is not repeated until the state changes. An editor found later is compiled once on arrival when the latest build transpiled; after a failed one, the next successful rebuild compiles it.
  • With --hot-reload, the reload answers first. A hot reload into a running game returns the same verdict, so no separate compile follows it. When no game is running the editor declines the reload, and the compile runs instead.

If you want one reload rather than a loop — a script or an agent that builds, reloads, and then decides what to do next — use reload, which posts a single reload, reads the console for a bounded window, and exits with a status you can branch on.

Flags

  • --hot-reload — push a reload to the running game after every successful rebuild that changes a file (see Hot reload).
  • --editor-compile — compile in the attached Defold 1.13.2+ editor after every successful rebuild and every project file change, and print its errors (see Compile in the editor).
  • --json — stream the build lifecycle as newline-delimited JSON for agents and scripts. See Agent runbooks for the event stream. Each reload adds a reload event; a reload the editor declined because no game is running is silent, and one a Defold 1.13.2+ editor rejected carries its issues in editorIssues. A late editor's version notice arrives as an editorVersion event instead of on stderr. With --editor-compile, each compile adds an editorCompile event.

As a mise task

mise run # and pick defold-typescript:watch
# or
mise run defold-typescript:watch
# with hot reload:
mise run defold-typescript:watch-hr
# with editor compiles, without and with hot reload:
mise run defold-typescript:watch-ec
mise run defold-typescript:watch-hr-ec

If you use mise, the scaffolded mise.toml exposes the loop as mise run defold-typescript:watch. Like build, it carries no version tag, so bunx resolves the @defold-typescript/cli that init pinned as a devDependency — the version locked alongside your @defold-typescript/types.

Footnotes

  1. src/ is this guide's shorthand and the scaffold's default, not a fixed location. Your source roots are the include globs in tsconfig.json — ["src/**/*.ts"] out of the box, and any list of folders you set; build and watch compile exactly what those globs match, and ignore exclude. ↩

On this page