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 watchTip
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-reloadFour 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 unreadabletsconfig.jsonends 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
watchlooks 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_scriptreloads 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-compileEach 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 valueHow 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
watchwrites itself,build/,.internal/,.git/, anything undernode_modulesor.defold-types, and any path your.defignorelists are skipped. Edits to.defignoreapply 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 areloadevent; a reload the editor declined because no game is running is silent, and one a Defold 1.13.2+ editor rejected carries its issues ineditorIssues. A late editor's version notice arrives as aneditorVersionevent instead of on stderr. With--editor-compile, each compile adds aneditorCompileevent.
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-ecIf 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
-
src/is this guide's shorthand and the scaffold's default, not a fixed location. Your source roots are theincludeglobs intsconfig.json—["src/**/*.ts"]out of the box, and any list of folders you set;buildandwatchcompile exactly what those globs match, and ignoreexclude. ↩