Changelog
What changed in each published defold-typescript toolchain release.
Tip
Upgrading the toolchain and upgrading your pinned Defold target are independent moves.
v0.68.0 - 2026-11-20
Summary:
go.animateandgo.setcheck the value against the property, andfactory.createandcollectionfactory.createcheck spawned scripts' properties (Component properties).- A scene address types its property keys, so
go.geton a linked script or a built-in component such as a sprite or a sound reads that component's catalog (Scene types).onMessage?.()and(onMessage)()report an error instead of crashing the build, and wrappedonMessage,defineScriptandresourcemarker calls are checked like the bare call (Which handler forms build).- More calls the engine raises on or ignores are type errors, such as a misspelled
gui.cancel_animationsproperty (GUI node properties) or afactory.createproperty map keyed by hash (Component properties).
Improved
- Property keys and values are checked against what the target declares:
go.animatechecks its target value against the property: on a transform key a number fills a vector such as"position"and"rotation"takes only a quaternion, andgo.animate<P>()takes a component catalog such assprite.Propertiesor aScriptPropertiesOfshape and accepts only the keys the engine can animate.go.setrejects a wrong value on a transform key too, such as a quaternion for"position", instead of accepting it as an untyped write (Component properties).go.get,go.setandgo.animatetype a property key by its address:scene-typeswrites each component address that names no compiled script as its kind, such as"sprite", instead oftrue, so a linked script's address takes only its declared properties, a sprite, label, model, mesh, collision object, factory, collection factory, particle effect, sound, tile map, camera (Defold 1.13.0 and later) or gui address types its catalog's keys, and a literal with no#, such as".", takes only the transform keys. An extension can register its own kind inSceneComponentCatalogs(Scene types).factory.createandcollectionfactory.createcheck the spawned scripts' properties in their curried forms:factory.create<P>()takes aScriptPropertiesOfshape asPandcollectionfactory.create<P>()maps each instance id, such as"/enemy_leader", to one, so an unknown id, an undeclared name or a wrongly typed value inpropertiesis a type error. The build removes the empty call and hashes each instance id, and reports a storedcollectionfactory.create<P>()or apropertiesvalue that is not an object literal as an error (Component properties).
Fixed
- Calls the engine raises on, ignores or animates wrongly are type errors:
collectionfactory.createtakes instance ids as hashes only: itspropertiesis a map keyed byhash("/enemy"), such as aLuaMap<Hash, EnemyProps>, so an object literal keyed by id strings, which the engine raised on at spawn, is a type error;collectionfactory.create<P>()takes the ids as strings and hashes them (Component properties).factory.createand eachcollectionfactory.createinstance table take aLuaMapof properties only when it is keyed by name strings and holds property values, so ahash("speed")key, which the engine skipped, or aMatrix4value, which made it drop every property, is a type error (Component properties).gui.animatechecks its target against the property the way the engine reads it:"rotation"takes only a quaternion, so a vector3 or a number, which animated to a distorted rotation, is a type error, and a sub-key such as"position.x"or a scalar such as"fill_angle"takes only a number (GUI node properties).gui.cancel_animationsandgo.cancel_animationsreject a property name the engine raises on, such as"positon":gui.cancel_animationstakes the namesgui.animatetakes, andgo.cancel_animationsthe keys a literal address can animate, so a script property holding aHashis a type error too (Component properties).gui.getandgui.settake anoptionstable holding one ofindex,keyorkeys, so a table holding two, which the engine raised on, is a type error (GUI node properties).physics.set_shapeon Defold 1.13.2 and later takes one table per shape kind, so a box withoutdimensionsor a hull shape, which the engine raised on, is a type error.sys.saveandsys.serializereject aLuaMaporLuaTablekeyed by anything but a string, number orHash, which the engine raised on.
http.requestaccepts theproxyoption the engine reads on native builds, which was a type error.- Wrapped and optional calls to
onMessage,defineScriptand theresourcemarkers build like the bare call:onMessage?.()and(onMessage)()report an error instead of crashing the build and the editor's diagnostics,onMessage!({...})and a hook written(onMessage)({...})lower,onMessage?.(handlers)squiggles once, and aresource.atlasdefault inside(defineScript)({...})compiles. A marker call such as(resource.atlas)("/a.atlas")outside a property default fails the build likeresource.atlas("/a.atlas")(Which handler forms build). - A component address stays untyped when the components behind it disagree:
scene-typeswrites it astruewhen two objects in the collection a factory spawns give a bare#iddifferent scripts or kinds, or when two proxied collections sharing one socket declare a path such as"level:/hero#body"differently.msg.post,go.get,go.setandgo.animatethen check it against no single one of those components (Scene types). - The docs sites show pages as written:
- Code blocks on both sites show at full length instead of scrolling inside a 600px frame, and the copy button shows a hand cursor on hover.
- The page outline on both sites keeps each heading's inline code, bold, italic and struck text instead of plain text.
- The API landing page leaves space between each group's description and its cards.
- Linked badges, such as those atop the Overview page, show without a link underline.
v0.67.0 - 2026-11-18
Summary:
builddeletes the runtime files nothing requires and keeps every file your sources compile to, under any letter case (Build).- Both docs sites have a new Fumadocs layout with in-browser search and guide and API pages rendered with Fumadocs' code blocks and callouts, and the toolchain site has section tabs and the API version range picker in the sidebar (API reference, library docs).
build,watchand the editor warn on a top-level name that hides a Lua or Defold global, such as a helper namedselect, andbuildandwatchprint the directgo.propertycall warning (TypeScript gotchas).
Improved
-
build,watchand the editor warn when a top-level name you do not export hides a Lua or Defold global, such as a helper namedselectornext, anenum go, or an import the file reads as a value, since each compiles to a Lualocalthat also catches the Lua the build generates in that file. The warning names the file, line and column, and the build still succeeds (TypeScript gotchas). -
The docs site has a new layout built on Fumadocs, with Get started, Guides, API and Libraries as tabs in a bar that stays at the top of the page, Get started opening on the Overview and Guides and API on a landing page, a page outline that shows each API signature in its syntax colors, a sidebar that lists every link of its tab in the page's HTML, closed folders included, with the API version range picker at its top, whose saved range or a link's
?since=the sidebar's count pills and the outline's change chips follow, and guide and API pages rendered with Fumadocs' code blocks, callouts and code tabs, guides under the heading anchors GitHub gives the same file. A search dialog (Ctrl+Kor⌘K) runs in the browser, tolerates a typo, finds API members by full or bare name, such asgui.animateoranimate, from the engine version of the page you are on, and shows each hit as the passage around your words, opening the member or the guide section under any heading it matched, or from its footer a/searchpage of up to 30 hits that you can link to. -
The library docs site has the same Fumadocs layout, with its guides and every library grouped by owner in a sidebar that lists all of them in each page's HTML, closed folders included, the Toolchain docs and GitHub links beside them, a page outline that shows each API signature in its syntax colors, and the toolchain site's search dialog, which runs in the browser, tolerates a typo, finds library members by full or bare name, untyped libraries and guide sections, and shows each hit as the passage around your words, opening the section or member it matched or, from its footer, the site's
/searchpage. Guide and API pages render with Fumadocs' code blocks, callouts and code tabs, each code block with a copy button and light and dark highlighting, and guides keep the heading anchors GitHub gives the same file.
Fixed
buildandwatchprint the warning for a directgo.propertycall, naming the file, andbuild --jsoncarries it inwarnings(Why not callgo.propertyyourself).- The API reference heading of
window.set_listenershows its whole signature in its syntax colors, which the backticks in its event type cut short, and links itswindow.EventDatatype. - A
buildwith no errors deletes the runtime files nothing requires any more, such as alualib_bundle.luaan earlier failing build wrote, ortimers.luaandhsm/<module>.luaonce no source imports them; a file stays when it lacks the generated banner, when a source of yours compiles to that file, including under a differently cased name on macOS and Windows, or when a hand-written Lua or script file requires it by name, and a file kept that way keeps the runtime files it requires.buildnames the deleted files on a second line andbuild --jsonlists them inremoved, while a failing build and awatchrebuild delete nothing (Build, Agent runbooks). - On macOS and Windows,
buildandwatchkeep a source output whose path differs only in letter case from a runtime file an earlier version wrote at the output root, such asDefold_Typescript_Timers.luabesidedefold_typescript_timers.lua, instead of deleting it right after writing it (Build). - An API reference URL whose
?since=names the oldest tracked release keeps thatFromwhen the docs site moves it onto your saved To, instead of replacing it with the From you last picked (Reading the API reference over a range).
v0.66.0 - 2026-11-15
Summary:
- Breaking:
buildskips everything undersrc/test/, so game code there moves out (build).- Bun tests sit next to their modules or in
src/test/, whichupgradescaffolds anddefold-typescript:typecheckchecks, and stay out of the build (Test with Bun).build --jsonaddslualibRequiredBy, and agents check.guiedits (runbooks, build).initandupgradekeep atsconfig.json's comments andextends(init).- Walls clear
outDir, the starter scene parses, the debug launcher type-checks, and TypeScriptToLua 1.37.2 fixes several Lua output bugs (wall, debugging).
Breaking
build,watchandwallskip everything undersrc/test/, the folder for tests and helpers that need Bun's runtime: a module there writes no Lua and joins no program the build type-checks, so game code in that folder moves out. A wall atsrcexcludes the folder; runwall srcto rewrite an existing one (Build, Wall).
Added
- Bun tests type-check against the game's own types, without Bun's globals reaching game code, in either of two places:
- Next to the module it tests:
build,watchand the editor plugin skip every*.test.ts,*_test.ts,*.spec.tsor*_spec.tsfile under the source roots, so it writes no Lua and gets no build diagnostic. Starting it with/// <reference types="bun-types/test" />lets the project's owntsc --noEmitcheck it (Build). - In
src/test/, for tests that neednode:*orBun:initandupgradewritesrc/test/tsconfig.json, which extends the root config, andsrc/test/env.d.ts, which referencesbun-types, addsrc/testto the rootexclude, and bring a hand-made test config onto the same settings, replacing itsincludeandexcludeonly when they select other files; thedefold-typescript:typecheckmise task then runstsc --noEmit -p src/test/tsconfig.jsonafter the root check, with or without a rootoutDir. Each edit, a Bun older than thebun-typespin or different from an exact project pin, and Bun tests undertest/ortests/get one warning (Test with Bun). - The Test with Bun guide page explains where a test goes, each
src/test/setting and how to stub engine calls; the managedAGENTS.mdblock and the Write a test runbook point to it.
- Next to the module it tests:
build --jsonreports which outputs require the TypeScript runtime helper bundle: a successful result always carrieslualibRequiredBy, the sorted output paths whose Lua requireslualib_bundle, including files this run left unchanged, so a project that avoids the bundle can check it without scanning its output folder (Agent runbooks).
Improved
- The agent contract and the package
llms.txttell an agent how to check Defold resource edits: type-checking and a plainbuilddo not fully validate or compile.guior.collectionfiles, so they point atbuild --editor-compile --jsonwith the editor open. They also list@defold-typescript/types/src/lifecycle.tsfor script callback payloads such asInputAction(Install the agent contract, Compile in the editor). - A new project lists
bun-typesat the exact version 1.4.4 in place of@types/bun, andupgradeadds it beside an existing@types/bunentry, which stays (Helper scripts).
Fixed
- A root
tsconfig.jsonwith a comment or trailing comma madeinit,upgrade,buildandwallfail,init --forceandupgradedeleted itsextends,referencesandfiles, and the.vscode/*.jsonmerges dropped comments. Every config the CLI edits now changes one key or entry at a time, andbuild, the editor plugin and the merge count settings inherited throughextends(Init). - The
.vscode/defold-debug.tslauncher reportedCannot find name 'node:fs'under the project's TypeScript 6: it now referencesbun-typesitself, andupgraderefreshes an unedited launcher (Debugging). - A walled directory whose source imports a module outside it reported TS6059 in the editor and in
wall --checkwhen the roottsconfig.jsonsetsoutDir. Each wall now setsoutDirtonull; runwall <dir>once for any walled directory to rewrite existing walls (Wall). - A fresh project's
main/main.collectioncould not be parsed:buildprinted three warnings and skipped the unreachable-address check, andscene-typesleft/mainout of.defold-types/scene-addresses.d.ts. A scene file with several fields on one line now reads the way Defold reads it (Scene types). - Several Lua output bugs from the TypeScriptToLua compiler: the transpiler now requires TypeScriptToLua 1.37.2, which fixes
-(-x)printing as a Lua comment,breakandcontinueinside atrywithin a loop, and@noSelfon interfaces with call signatures. bun auditcould flag the CLI'shonoand@hono/node-serverdependencies: the CLI now requireshono4.13.18 and@hono/node-server2.1.8 or newer, which close the published advisories.
v0.65.0 - 2026-11-13
Summary:
Improved
- The gameanalytics types follow
GameAnalytics/GA-SDK-DEFOLDtag5.0.0: they add the user and A/B-testing id getters withgameanalytics.setExternalUserId, the session-time getters, the number and JSON remote-config reads, and four health-event toggles such asgameanalytics.enableFpsHistogram.gameanalytics.addBusinessEventacceptsreceipt,signatureandautoFetchReceipton every platform.
Fixed
- Code tabs, copy buttons, hover tooltips and live state machine demos could stay dead on a long docs page when the end of the page arrived after the site's script had run, which a cached script makes likely: Opera on Windows showed it on the Config/Builder tabs of the State machines guide and the TypeScript/Lua tabs of reference pages such as vmath. Every page now sets them up once it has fully loaded.
v0.64.0 - 2026-11-12
Summary:
onMessagehandlers and hooks bind every parameter and module-level name at runtime, and a defaulted one fails the build (Which handler forms build).
Breaking
- A defaulted
onMessagehandler or lifecycle hook parameter, such asupdate(self, dt = 0), fails the build with an error at that parameter, since the default never took effect. Default it inside the body (Which handler forms build).
Fixed
onMessagehandlers and lifecycle hooks built clean but read the wrong value or an undefined global when Defold ran them: a handler reading itsselfparameter or a module-levelmessage,senderormessage_id, a parameter TypeScript-to-Lua renames such astype, handler parameters named after another engine argument such as(message, msg), and an optional parameter past the engine's arguments on a handler or a returninginit. A handler now reads every module-level name it uses and each parameter holds the engine argument at its position, orundefinedpast them, while a destructured or rest parameter, which emitted broken Lua, fails the build at that parameter (Routing many messages, Reading properties ininit).
v0.63.0 - 2026-11-12
Summary:
bun testrunshsmandecsfrom a plain import (State machines).buildandtscagree ononMessage, socket aliases and the API and libraries an editor or game script may use (Editor scripts).- Interface values pass as tables to
sys.saveand everyPlainTableslot on all targets.- Clean scaffolds that
upgradekeeps current: docs paths,.gitignoreand Biome (init).- Symbolic links and
outDir:buildandwatchcompile a linked folder anincludepattern reaches inside the repository or alink-rootsfolder,build,watchandresolverefuse to write through a link or outside the project, and anoutDirDefold never loads, or a source insideoutDir, failsbuildandwatch(Linked source folders).
Breaking
- An
outDirDefold never loads is rejected, and a source insideoutDirfails. Atsconfig.jsonoutDirthat is absolute, climbs out with.., or is or sits inside a rootbuild,builtins,.internalor.gitfolder or a folder.defignorelists, in any letter case, makesbuild,watch,setup-debugandscene-typesfail with a message naming the setting and write nothing; move it to a folder such asout. A source insideoutDir, whichtscnever type-checks, failsbuildandwatchuntil you move it out (Build). - A source under a linked folder needs an
outDir, and a link leading out of the repository needslink-roots. A project with nooutDirwhoseincludefolder, or a folder under it, is a symbolic link fails the build, naming the link, and so does a link thatincludereaches whose target is outside the repository (the project itself when no.gitsits at or above it) and everylink-rootsfolder (Linked source folders).
Added
@defold-typescript/types/hsm,@defold-typescript/types/ecsand their sub-modules run underbun test, so a machine or a world can be unit-tested with a plain import and no Defold engine. See State machines and Entity systems.buildandwatchcompile sources behind a symbolic link anincludepattern can reach, as if they sat at the link's path, when the link leads inside the repository or a folder listed inpackage.json"defold-typescript"."link-roots"; the pattern matches through a link as in a real folder, and one file reached under two paths fails the build, naming both.watchrebuilds and hot-reloads on an edit inside a linked folder at every link path that reaches it, also after the folder holding a link is renamed (Linked source folders).
Fixed
build,watchandresolvewrote through a symbolic link at an output, source-map or runtime folder path, at.gitignoreortsconfig.json, or through a folder link such as.defold-typesleading out of the project, so a cloned repository could make them create, overwrite or delete files anywhere you can write. They now refuse that write and name the path, the link and where the link points (Build).watchskipped edits to a source thatbuildcompiled when itsincludepattern started with./or held a character class or brace list, such as./src/**/*.ts,src/**/[su]*.tsorsrc/{game,ui}/**/*.ts, andsetup-debugread those patterns the same wrong way. Both now matchincludeasbuilddoes (Watch).- On macOS and Linux, a backslash in a
tsconfig.jsonoutDirnamed one folder (out\lua) while the debug launcher looked inout/lua. It now separates folders as on Windows, so delete any leftoverout\luafolder (Build). buildandwatchlisted every output inwrittenand thewrote N filesline, even one whose bytes had not changed, andwatch --hot-reloadreloaded the game after a rebuild that changed nothing. They now list only files the build created or changed, andwatch --hot-reloadreloads only after a successful rebuild that changed a file, counting files an earlier failed rebuild wrote (Hot reload).setup-debugandscene-typesignored an invalidpackage.json"defold-typescript"."runtime-dir":setup-debugwired the project for thesrc/default layout andscene-typeswrote a declaration with no script links. Both now fail with the messagebuildgives and write nothing (Build).onMessageand the socket type aliases such assocket.TCPOptionstype-checked inbuildbut not undertscor in the editor: on every Defold target a project'stscreportedCannot find name 'onMessage'and found noTCPOptionsin thesocketnamespace. Both now resolve intscand the editor as they do inbuild(Routing many messages).buildandwatchchecked every source against the editor and runtime surfaces merged, so a game script callingzip.packoreditor.commandbuilt clean while an editor script callingimage.load_fileorhttp.server.responsefailed. Each side is now checked astscchecks it: an editor script and every helper it imports, directly or through a re-export, against the editor surface plus the bundledhsmandecslibraries, your own.d.tsfiles and the Lua libraries resolve installs, but no native extension, and every other source against the runtime one (Editor scripts).sys.save,sys.serialize,json.encode, thepropertiesoffactory.createandcollectionfactory.create, thevalueofeditor.tx.add, editor and native extension option tables, and library parameters typed as a table of any value rejected a value typed by an interface. On every Defold target these slots now take aPlainTable, which accepts an interface value as well as an object literal or atypealias, while engine values such asVector3,HashandUrl, functions, coroutine threads and Lua userdata such as file handles are rejected.- A scaffolded project fell short of a clean setup in three places; init writes the fixes and upgrade adds them to an existing project:
- Docs paths: the managed
AGENTS.mdpointed at docs missing under Bun's isolated installs, so the scaffold now lists@defold-typescript/docsin its dev dependencies, pinned to the CLI's version. .gitignore: generated.ts.editor_scriptfiles and.lua.mapfiles outside component output reached version control; the managed rules now ignore both.biome check: a new project reported a schema-version notice and auseBiomeIgnoreFolderwarning. The scaffold now pins Biome exactly to 2.6.7, the version itsbiome.jsonschema names, and ignores.defold-typesthe way Biome 2.2+ expects;upgrademoves an older exact pin together with the schema naming it, and keeps any other Biome version or schema you chose.
- Docs paths: the managed
v0.62.0 - 2026-11-10
Summary:
- Defold 1.14.1 is the default API target (what changed), with recorder typed.
start_recordandstop_recordlose their message types; recorder replaces them.
Breaking
- The built-in message types no longer declare
start_recordorstop_record, which Defold 1.14.1 removes in favor ofrecorder.startandrecorder.stop. A project pinned to 1.14.0 or older that still posts them does so through the untypedmsg.postarm.
Improved
- Defold 1.14.1 is the default API target, so a project that pins no target compiles against it, and code written against 1.14.0 compiles unchanged. Upgrading Defold versions lists the engine and project changes the compiler cannot check, and
--defold-target 1.14.0keeps the previous surface. - Defold 1.14.1 APIs are typed:
recorder.startandrecorder.stoprecord the game window to an MP4 file,window.get_reserved_areasreturns the screen areas a camera cutout covers,graphics.CONTEXT_FEATURE_BACKBUFFER_READBACKjoins the context features,sound.set_gain,sound.set_panand their messages take aplay_idto change one voice,sys.reboottakesarg7andarg8, theon_inputaction carries its inputsource, and editor scripts geteditor.resource_children. The engine debugger'sdebugger.startstays untyped because the API reference does not document it, and Calling the engine debugger from TypeScript shows how to declare and call it.
v0.61.1 - 2026-11-10
Summary:
resolvelists the debugger without a notice.- Dependency warnings name
resolveas the fix.
Fixed
resolvetreated thelldebuggerdependencysetup-debugadds as a library nobody types: it listed it asasset-only, skippedand named it in the notice to declare its modules insrc/types/, thoughsetup-debugalready declares the one module a project requires from it.resolvenow lists it aslldebugger.debug <- <url> (debugger, declared by setup-debug)and leaves it out of the notice, which still names every other untyped dependency (A library nobody types);--jsonleaves it out ofnoticestoo.- A warning about a dependency
resolvehad not materialized did not name the fix: the reasonbuild,watchandscene-typesprint for it, and for a materialized dependencygame.projectno longer declares, now ends withrun `defold-typescript resolve`(What it does);--jsoncarries the same string inwarnings.
v0.61.0 - 2026-11-10
Summary:
- Libraries are named by
host/owner/repo, and a library on an unknown host gets no types.minClikeeps a library from a CLI too old to read it.- Untyped Lua gets a
resolvenotice on typing it yourself.- Four new
misetasks type-check, regenerate scene types, launch throughboband pin the editor's Defold version.
Breaking
- Library data names each library by its lowercase
host/owner/repo(Library data), the name lockfile pins, thelibrarycommands' folders, the--jsonsourceof aresolvematch and each library page address (/api/<host>/<owner>/<repo>/<namespace>) use; a pin an earlier CLI recorded under a bare repo name is pinned again at the newest data. A dependency on a host no library's repository is on, such as a company git server or an IP address, matches no library data (Vendored library types).
Improved
- A dependency matches the library holding its exact
host/owner/repo, else the one library sharing its repo name, so a fork on any host a library is on keeps its upstream's types and library status with a notice that they may not fit, and a repo name two libraries share types the dependency with neither, with a notice (Vendored library types).resolve --update=<name>, thelibrarycommands andexport-typestake any trailing part of a library's name (monarch,britzl/monarch,github.com/britzl/monarch), andexport-typesalso a dependency URL. - A library's
library.jsoncan setminCli, the first CLI release that reads it: an older CLI reads no data for that library, soresolvetypes it from the dependency's own archive and thelibrarycommands leave it out (library). resolveadds one notice naming every dependency that shares Lua nothing types, linking a new guide section that shows how to declare its modules insrc/types/<library>.d.tsand how to share them upstream (A library nobody types).initandupgradescaffold four moremisetasks (Opinionatedmise.toml):defold-typescript:typecheckruns the project'stsc --noEmit,defold-typescript:scene-typesrunsscene-types,defold-typescript:bob-runrunsbuildthenbob run, anddefold-typescript:sync-targetrunsset-target --detected.
Fixed
library addrefuses a repository URL whose host, owner or repo holds anything buta-z,0-9,.,_and-, before it downloads, so it writes only inside the data folder: on Windows a backslash in the repo could write outside it (library).- On a phone, opening a link to a heading in the guide, the API reference or the library reference shows the heading below the top bar instead of behind it.
v0.60.0 - 2026-11-09
Summary:
- Library pages move to
/api/<owner>/<repo>/<namespace>, and members link and search by name, such asgui.new_spine_node.- gameanalytics and mpeg.gui_video are typed, and proto drops its compiler's types.
resolvereads[options]as optional and types a native namespace beside a Lua library, such asdefsave_ext.- Library pages put no
?before a required argument and install unreleased repos from a pinned tag or commit.- Editor scripts import their factories and types only from
@defold-typescript/types/editor-script.
Breaking
- Every page on the library docs lives at an address named by its library's repo (Library page addresses): an API page at
/api/<owner>/<repo>/<namespace>(/api/defold/extension-spine/gui,/api/insality/druid/druid) and an untyped library at/libraries/<owner>/<repo>, all lowercase. The flat/api/<name>addresses are gone, so links and bookmarks to them need the new form. - proto declares only its own API:
proto.Lexer,proto.Parser,proto.toplevel,proto.msg_bodyandproto.svr_body, internal types of its bundled protobuf compiler, are gone from its declarations and API page.proto.init,proto.encode,proto.decodeand its other functions are unchanged. - Editor scripts import
defineEditorScript,defineEditorCommand,EditorCommandandEditorScriptModuleonly from@defold-typescript/types/editor-script(Editor scripts), which now exports the two types beside the factories. The bare@defold-typescript/typesentry exports none of them, so an editor import from it is a compile error; move it to the subpath.
Improved
- Every druid and decore parameter has a real type where it was an optional
unknown:druid.druid_container.remove_container_by_nodetakes anode,druid.druid_layout.set_node_positiontakes abooleanis_instant,decore.system_bus_event.onAddToWorldtakes aworld, and druid's internal scroll, drag and container methods take numbers, hashes, actions and touches. - A curated gameanalytics module types
GameAnalytics/GA-SDK-DEFOLDtag4.2.6(Curated native extensions): each event function takes a table with its required fields and only the enum spellings the extension accepts, and the remote-config getters return strings and a boolean. Its library page has you install from the repo's tags, naming the4.2.6tag archive, since the repo publishes no releases. - mpeg.gui_video types the GUI video player of
Morgerion/defold-mpegtag1.2.0:mpeg.gui_video.inittakes a node, avideo_resourceorvideo_data, and the playback and sound options, andmpeg.gui_video.update,mpeg.gui_video.finalandmpeg.gui_video.is_finishedtake the player'sfield. - The
.script_apinamespaces of an Asset Portal library typed here have library pages of their own beside its module's: defsave_ext forsubsoap/defsaveand mpeg forMorgerion/defold-mpeg.
Fixed
resolvedeclares a.script_apiargument named in brackets ([options]) optional (The generated surface), not as a requiredarg0, and when a required argument follows it also declares the call without it, soopen_file(callback)andopen_file(options, callback)both compile.resolvewrites the.script_apinamespaces a typed Lua library's archive documents beside its module (Vendored library types):subsoap/defsavegetsdefsave_extandthejustinwalsh/defold-zzfxgetszzfx_extin.defold-types/extensions/, beside their module types, andresolve --jsonlists them in that dependency'snamespaces.- Library docs pages match the code you write and the archive you install:
- Member names link, tooltip and search as you write them on the pages for Spine's gui and
resource,extension-camera,extension-proto, the Firebase extensions,defold-rnganddefold-random:gui.new_spine_nodeis found as written, not asspine.gui.gui.new_spine_node. A name two libraries share links only on its own library's page. - Signatures put no
?before a required argument: such an argument readsT | undefined, as indefos.set_window_size,fusion.spawnand thewavedash,playables,poki_sdkandvideoplayerpages, and the browser_io page lists each call with and without itsoptions. - Install steps for a repo with no stable release name its pinned tag or commit archive, not its releases page: log, tweener, event, dicebag, defmath, ink and eleven other library pages.
- Member names link, tooltip and search as you write them on the pages for Spine's gui and
v0.59.0 - 2026-11-07
Summary:
hsm/builderwrites a machine as calls, andviewglows the call that fired.
Improved
- Write a machine as statements:
buildMachinefrom@defold-typescript/types/hsm/buildertakes a skeleton of the machine's states, checked as a config is, and statements such asm.state("/off").on("TOGGLE").to("/on"),after,every,always,enterandexitadd its behavior, with every path and event checked at compile time.build()hands the result todefineMachine, so the key, hot reload andviewwork as for a config, with each fired rule glowing on the call that made it; it throws, naming the state, on a rule left without its ending.
v0.58.0 - 2026-11-06
Summary:
- An Entity Component System,
ecs, ships built in, with string filters, hot reload, state hooks that move an entity between systems, a world inspector, an editor hover on every export, and a hands-on tutorial.viewreplaceshsm-viewand runs a file's script,ecsworlds and machines on one clock, with a Worlds tab of systems, entities and timings linked to the code.- Script callbacks run beside a top-level import or declaration of the same name.
Breaking
hsm-viewis renamedview: rundefold-typescript view <file> [name], where[name]picks every machine and world of that name. Its--jsonline reads"command":"view"and adds the pickedworld.
Improved
- The
ecsEntity Component System ships with the toolchain: import@defold-typescript/types/ecs, andbuildandwatchwrite its tiny-ecs port toecs/index.luain the runtime folder, MIT license header kept and listed in the CLI'sTHIRD_PARTY_NOTICES.md, each file written only for projects that import it for values.requireAll,requireAny,rejectAllandrejectAnythrow on a token that is neither a component name nor a filter,undefinedincluded.- String filters:
filter("a&!(b|c)")builds a filter from a tiny-ecs pattern, and a misspelled component in a literal pattern fails to compile. A pattern outside tiny-ecs's documented syntax throws, andtryFilterreturns the error instead. - Hot reload:
system,processingSystem,sortedSystemandsortedProcessingSystemtake an optional key. Whenwatch --hot-reloadorreloadruns the edited module again, a keyed factory puts the new definition into the system it built first, and the world keeps running that system with its entities. - ecs and hsm together: import
@defold-typescript/types/ecs/hsmto make one table both an entity and an hsm machine'sctx, whosemember,joinandleavestate hooks change which systems hold it whiletickMachinesupdates the machines. - Debug a world:
inspectfrom@defold-typescript/types/ecs/debuglogs each entity a system gains or loses and eachonModifycall, keeps logging across a keyed reload, and draws each system's entity count over a game object; in a release build it does nothing. - Editor hovers: every export of each module, and every system field and callback, shows a one-line summary, its parameters and return, and an example that compiles; the Reference tables quote the same summaries.
- Entity systems, one system at a time: a hands-on tutorial grows one night garden of fireflies lesson by lesson, until it uses every export of the three
ecsmodules. Each change is a diff that compiles, and each lesson shows the console its code prints under the realecs. - The
AGENTS.mdblock thatinit,upgradeandinit-agentswrite listshsmandecswith their import paths and guide pages.
- String filters:
viewruns a file's machines, script andecsworlds on one page and one clock:- Worlds tab: lists the picked world's systems with their entity counts and timings, opens each one's entities as read-only trees, and links each system to its definition in the code and back. The page opens on it unless
[name]picks a machine or the file creates no world, and the log notes each entity that joins or leaves a system. - Script lifecycle: a
defineScriptscript'sinitruns once, and each frame calls itsupdate(or each world's) before the machine's. A reload keepsselfand the worlds and callson_reload. - One clock:
tand the frame count are the run's time, which Start leaves running, and Restart reruns the files andinitfromt0. - Follow an instance: the bar's instance dropdown, or an entity's link on the Worlds tab, shows a machine instance the run started in place of the simulated one, its states tinted as the run moves it.
- Simulated engine values: Lua's
math(the same numbers on every start),os.clock,vmath.vector3,vmath.vector4,factory.create,msg.url,go.get_position,go.get_world_position,sys.get_engine_infoandsys.get_config_stringreturn simulated values instead ofundefined, andecsfilters reject a bad token as they do in a game.
- Worlds tab: lists the picked world's systems with their entity counts and timings, opens each one's entities as read-only trees, and links each system to its definition in the code and back. The page opens on it unless
Fixed
- A script callback named like a module-level binding never ran: a script that imported or declared
update,init,on_messageor another callback's name at the top level built cleanly, but the engine never called that callback. It now runs, and its body still reaches the binding of the same name.
v0.57.0 - 2026-11-04
Summary:
- Forked library types show the library's own docs on hover.
Improved
- Forked library types carry the library's own docs:
resolveprints each member the library documents with its doc summary and the parameter and return docs for the signature the fork declares, unless a hand-written fork's own comment is pinned to that exact text with@upstreamDoc, so your editor shows on hover what the member's library API page shows.library checknames each fork comment that prints the library's doc instead, with the pin that would keep it, and does not fail for it.
v0.56.0 - 2026-11-03
Summary:
- Library types update without a CLI release, each library pinned until
resolve --update[=<name>].- Library status says whether each library's commit was reviewed, and
library updatemoves each library to its newest upstream commit, naming what the move did to its members.defold-typescript.lockholds whatresolverecords; commit it, sinceresolve --frozenneeds it to check the archivesbob buildwill read.resolve --pin-urlsmoves branch and tag URLs ingame.projectto commits, andresolvewarns about each branch URL.- Library API pages moved to their own site, with no redirects.
Breaking
resolvefetches library data itself: library types, and the index notes on curated extensions, come from the library data repo and update without a CLI release, and@defold-typescript/library-typesis no longer published.resolveandwatchpin each library you use at its own commit, so adding or moving one leaves the others' types alone, a notice names each library whose newer data changes more than its recorded reviews, andresolve --update[=<name>]moves what you ask for;export-typesreads the newest data.- Pins moved to
defold-typescript.lock:resolvekeeps its records in this committed file instead ofpackage.json, each dependency's entry holding its commit and a hash of the files a game can use, so changed files under an unchanged commit count as drift, whichresolve --updateaccepts. Runresolveand commit the file:resolve --frozenfails without it and when a declared dependency has no entry, and anyresolvefails on a lockfile that does not parse. resolve --frozenchecks what the build reads: once.internal/lib/dependencies.jsonexists, it reads only that folder and fails, naming the URL, when the folder does not hold the one archive listed for a dependency, instead of downloading. Runbob resolve,resolve --frozenandbob buildin that order to stop a CI build whose libraries differ from your lockfile; see Dependency safety.- Library API pages moved: library pages and the Libraries index are on the library docs site, with no redirect from their old
/api/<library>and/librariesURLs, and this site's search no longer finds them. Their links to an engine member open this reference at that member, and the Libraries tab opens there in a new tab, marked as an external link.
Improved
library updatefollows upstream: it records each new commit, from the tags or default branchfollowsnames inlibrary.json, whose hashes a review already holds, and moves the library to the newest that differs by re-copying its upstream files and never its forks, failing a library whose new commit no longer holds a file it reads with its folder untouched. Against the review that lists the pinned commit, it reports whether the movekeptevery member, onlyaddedsome orchangedothers, naming them, and readschangedwhen no single review lists that commit.resolve --pin-urlspins dependency URLs to commits: it rewrites each GitHub branch or tag URL ingame.projectto the commit its archive names, never over a dependency saved during the run, andresolve --updatethen follows the original ref inside that repo.resolveandwatchwarn about each branch URL, and--jsonreports each dependency's kind of URL asref.- Releases check the library data they publish: a release publishes only after
library checkpasses with that release's CLI on the library data from the same commit, and only once the library data repo serves exactly that data. A nightly run checks that data with every published CLI that reads it, so data a published CLI fails on is reported. - Library docs update on every data merge: the library docs site rebuilds with each library data merge rather than each toolchain release. The guides for adding a library and refreshing its pin are there too, and the
library addnotes link to them. resolvereports each library's status against what library data reviewed:resolve --jsoncarries it aslibraryStatusand the plain report names every library that is notexact, from API, doc and source hashes thatlibrary addandlibrary review --data <dir>record. A failed download fails that library's review with its record untouched, even with a cached copy.
Fixed
- Doc comments and API pages keep upstream text that only looks like a tag: declarations lost everything from a
<to the next>, so therandomlibrary's probability doc readValues = 1 are always true. Text such asValues <= 0andparticlefx.EMITTER_STATE_<STATE>now comes through whole. - A
game.projectwith CRLF line endings keeps its dependencies: itsdependencies#Nlines read as absent, soresolveandwatchremoved the project's dependency types and the scene walk saw no dependencies.
v0.55.0 - 2026-10-31
Summary:
- Dependency types follow the archives Defold fetched, and their pins name a commit; a plain
resolvereplaces an oldsha256:pin.- Library types are printed from the library version the game depends on, and
resolve --library-datareads library data from a local directory.library addandlibrary checkstart a library's data folder from its archive URL, check it against this CLI's engine types and its coverage floors, and can write the API models the docs site renders.- Script properties compute their defaults at build time and register in the key order the source shows.
- The docs site documents the npm version.
Breaking
- Dependency pins name a commit:
resolvepins each dependency ascommit:<sha>, read from a GitHub archive's zip comment, or else asfiles-sha256:<hex>over the files itsinclude_dirsshare, so a pin moves only when the code a game uses does. A plainresolvereplaces asha256:zip-byte pin inpackage.json, andresolve --frozenfails on one until it has; see Pinning extension versions.
Improved
- Library types follow the library version the game uses:
resolveprints a matched library's declarations from the archive the project depends on, and prints the version library data pins with a warning when that archive cannot be printed; a library typed by a hand-written fork keeps its fork. See Vendored library types. - Library data from a local directory:
resolve --library-data <dir>reads library data from<dir>instead of the installed package. Library data sits in folders named by the first CLI version that reads them, and a CLI reads the highest one at or below its own version; see Flags. - Add and check library data:
library add <url> --data <dir>starts a library's folder from its archive URL, with its pin and, when its.script_apior annotated Lua can generate a module, a starting recipe and the upstream files it reads, and refuses a folder that already exists, even one created during the download, without changing it.library check --data <dir>runs the reader's checks, prints every module, compiles the declarations and usage examples against this CLI's own engine types and holds each module to its floor inlibrary.json, a module with no floor or below it being a problem, exiting 1 on any problem, and--api-doc-out <dir>then writes each library's API model; see library. - Script properties are computed at build time: a
defineScriptpropertiesdefault Defold's build cannot read as written, a spread, shorthand or const-keyed member, and apropertiesvalue that is not an object literal are evaluated in a sandbox and register one literalgo.propertyper name, in JavaScript's key order as read throughconsts and their spreads, imported ones included. A default that needs an engine API, randomness or a file, whose value is not a property type, or whose key order the source does not show, such as two names from a function result, fails the build with a diagnostic naming the cause, and the text-property version gate covers the strings a spread brings in.
Fixed
- Dependency types stayed at the first download:
resolveserved the copy it first cached of a moving archive such asmaster.zip, even after Defold's Fetch Libraries moved the game to newer code, andwatchre-resolved only on agame.projectsave. It now reads the archive Defold fetched into.internal/lib/when its commit matches, else revalidates its own cache by ETag and uses it offline with a warning, andwatchre-resolves after each Fetch Libraries; see Cache location. - Some libraries shared no scene sources: a library whose
include_dirsnamed a nested or slash-wrapped directory such as/monarch/transitions/, separated its directories with whitespace, or sat in agame.projectwith CRLF line endings gave scene types nothing to address. Each form is read, and every file beneath a declared directory is shared; see Dependency scene sources. - The docs site described unreleased changes: it was published on every push to
main, so a guide or API reference page could document behavior the version on npm lacks. It is now published once per release and documents that release. - Script properties dropped silently: a spread, shorthand, method, accessor or variable-keyed member of
defineScriptproperties, or a whole object wrapped inasorsatisfies, registered nogo.propertywhileselfstill typed it, and a default Defold's build cannot read, such as a module const, failed only in Defold's build. Each member now registers or fails the build, a literal key such as["a-b"]or0x10registers under its JavaScript name, and an infinite number registers as1e999.
v0.54.0 - 2026-10-28
Summary:
- Libraries ship their own types:
resolveinstalls a dependency'stypes/*.d.tsahead of every other surface, soking8fisher/defold-pixelsis used throughimport * as pixels from "pixels"(delete any copies of its files),export-typeswrites a curated library's types out for its author to ship, and a native extension's module declaration carries@globalTableso its imports compile to the extension's runtime global and build in the Defold editor.resolveextension declarations carry branded constants, optional parameters and typed callbacks, and none is lost when extensions share a namespace or differ only in letter case.- Native extensions are modules a script imports (
import * as iap from "iap"), the.script_apinamespacesresolvewrites and the curated ones alike, with no global left to call bare, and fourteen more extensions are typed, among them box2d, png and openal.resolveruns under Node and Bun on every OS for a project with a native extension, with nounzip, andbuildandwatchcompile a project using the types it installed.- Asset Portal libraries get reference pages from their
.script_api, LuaLS annotations, or declarations maintained here, including flow's facade, GamePush, Colyseus, ink, light and shadows, operator, def-behavior-tree, illumination, stylized water, defold-wrap's scenes and wrappers, the Minit publishing SDK and the asobi multiplayer client with its realtime and REST APIs.
Breaking
- A
.script_apicallback parameter is typed from its documented arguments in the.defold-types/extensions/<namespace>.d.tsthat resolve writes:iap.set_listenertakes(self: unknown, transaction: { ident: string; state: string; ... }, error: Record<string | number, unknown>) => voidwhere it took(...args: unknown[]) => unknown, so a listener declared with other argument types or a non-voidreturn no longer type-checks. A callback whose doc lists no arguments keeps(...args: unknown[]) => unknown. king8fisher/defold-pixelsis typed by the module its archive ships intypes/in place of its.script_api(Types a library ships): use it throughimport * as pixels from "pixels"where the globalpixelswas typed, and every buffer argument takes aPixelsBufferInfowhere it took any table. A project that copied upstream'stypes/files deletes the copies, which otherwise redeclare their names (TS2451, TS2300).- Native extensions are modules a script imports: write
import * as share from "share"where the bare global was typed. A bare use fails withCannot find name, and a type named through the namespace, such asshare.FileOptions, needs the import too:.script_apinamespaces that resolve writes, shared ones such asfirebaseand dotted ones such asrive.cmd(import * as cmd from "rive.cmd") included. A doc that adds members to an engine namespace, such as Spine'sgui, stays global.- The curated daabbcc, share, uuid4 and tile_raycast natives (Curated native extensions), so a call such as
uuid4.generategoes through the import.
Improved
resolveinstalls the declarations a dependency ships in a roottypes/folder (Types a library ships) unchanged under.defold-types/extensions/shipped/<repo>/, where they keep their names and may reference each other by relative path, ahead of a vendored library match, a curated native namespace or its.script_api, once they compile against@defold-typescript/typeswith each dependency checked on its own; files that add global names are left out when one file declares a module, and files that do not compile fall back with a warning.--jsonreportstypeSurface: "shipped", and library authors can follow Shipping types with a library.export-typeswrites a library's curated types into atypes/folder its maintainer can ship (Starting from the curated types):bunx @defold-typescript/cli export-types <library> [path]copies the declarationsresolveinstalls for the library today, unchanged, and writes nothing unless thetypes/folder the file system will hold, files already there included, would install with every exported file and pass the checkresolveruns on shipped types. Where the file system ignores letter case, an existing file whose name differs only in case is the one an exported file overwrites, and it keeps its name.- A native extension typed in module form builds in Defold with
@globalTable(Module-form native extensions): tagging the ambientdeclare modulewith/** @globalTable [name] */makes every import of it — namespace, named, re-export or dynamic — compile to a local alias reading the extension's runtime global through_G, so no project local shadows it, the built Lua carries norequireof a module no file provides, and the Defold editor and bob load it. A tag naming an invalid Lua global fails the build with the file and line. resolveextension declarations carry the whole documented surface: the namespace's constants, including those one sub-table deep (iap.PROVIDER_ID_GOOGLE,push.NOTIFICATION_BADGE), each branded as thestringornumberits doc declares (firebase.analytics.EVENT_ADIMPRESSIONis astringbrand), a function returning a documented constant typed as that constant union, a parameter flaggedoptional: trueemitted optional, and a table parameter typed from its documented fields. A.script_apislot typedenumis read as a constant-valued slot, sowebview.create's callbacktypeargument is the union of thewebview.CALLBACK_RESULT_*constants.- The facebook, playables and poki_sdk Libraries pages show the parameter types their
.script_apispells as YAML lists ([string, nil]), which previously rendered as untyped. - Library pages define the types their signatures name: a union, function-type or other non-object alias such as
monarch.monarch.ScreenIdorrichtext.richtext.Alignmentshows its definition (type ScreenId = Hash | string) and the signatures taking it link to it, and an interface named only by another interface's field, such asyagames.MultiplayerSessionEventornode_repeat.RepeatFrame, gets its own entry. An interface shows the interface it extends, such asplatypus.PlatypusInstance, and its call signature when it is callable, such asdefcon.CommandCallback. - Libraries lists the Defold Asset Portal's libraries under their GitHub owners: one that ships a
.script_apigets a reference page per doc, such as defos, and one that ships no Lua API, such as shaders, materials and editor scripts, gets an icon-marked page, such as defold-sharp-sprite. Each page gives the dependency step for its pin and links the library's Asset Portal entry. - A Defold extension or Asset Portal library page pinned to a release or tag names the Defold version current when it was cut (Browsing Defold's own extensions): iap reads
released while Defold 1.13.1 was currentbeside its pin, as do portal pages such as astar and defold-sharp-sprite, a hint at the pin's age rather than a compatibility promise. - More Asset Portal libraries are typed, from their LuaLS annotations or, for a library that ships none, by declarations maintained here: declare the dependency and
resolvewrites its typed module. quest and token importeventfromInsality/defold-event, so a project using either one declares defold-event beside it.- detiled (
Insality/detiled, tag3) —detiled.parsereturns a Tiled map's layers and map params, whichdetiled.cell_to_posanddetiled.pos_to_celltake to convert between cells and positions. - token (
Insality/defold-token, tag9) —token.containerreturns a container whosetoken.token_container.getreturns anumberand whose change events take a callback alone, as they do in Lua, andtoken.on_token_change,token.on_token_visual_changeandtoken.on_token_restore_changeare exported as module-wide events. - quest (
Insality/defold-quest, tag3) —quest.eventreports a game event to the active quests,quest.start_questreturns whether the quest started, and thequest.on_quest_eventqueue and thequest.is_can_start,quest.is_can_completeandquest.is_can_eventchecks are exported for subscribing. - pigeon (
paweljarosz/pigeon, tagv1.5) —pigeon.send_totakes any receivermsg.posttakes (aUrl, a URL string or ahashid), andpigeon.sendposts to every subscriberpigeon.subscriberegisters. - live_unbundler (
HGPoint/defold_live_unbundler, tag2.3) — the module's unannotated constants are exported: theres_modevalues such aslive_unbundler.RES_BOTHthatlive_unbundler.inittakes, theHashmessage ids such aslive_unbundler.MSG_ALL_LOADEDits listeners receive, and the log levelslive_unbundler.set_log_functionpasses. - ads_wrapper (
potatojam/defold-ads-wrapper, tag1.5.1) —ads_wrapper.ads_wrapper.register_networkreturns a network's id or nil and accepts the test networks, such asads_wrapper.ads_networks.test.network1, and twelve ad-SDK network modules, such as ads_wrapper.ads_networks.vk, ads_wrapper.ads_networks.applovin_max and ads_wrapper.ads_networks.admob, whose declarations are maintained here, each typed with its own functions and constants. The ads_wrapper.events hashes, the ads_wrapper.platform checks and the ads_wrapper.queue functions are typed too, whereads_wrapper.queue.addtakes a function called as(network, callback, params). - fake_real_glass (
paweljarosz/defold-fake-real-glass, tagv1.1) — the defold-glass render module:fake_real_glass.createtakes a probe mode typed as its three values, such asfake_real_glass.PROBE_MODE_EVERY_FRAME, and thefake_real_glass.MSG_SET_PROBE_POSITIONandfake_real_glass.MSG_SET_PROBE_SETTINGSids thatfake_real_glass.on_messagehandles are exported. - hyper_trails (
indiesoftby/defold-hyper-trails, tag1.4.2) —import * as trail_maker from "hyper_trails.trail_maker", whose functions, such ashyper_trails.init_vars, take the script'sselfor a plain options table. - pixelart.scripts.pixelart (
selimanac/defold-pixelart-shader, commit8db334d) —pixelart.scripts.pixelart.initrequires the pixel size and edge coefficients and takes optional light and shadow settings, and a render script passes itsselftopixelart.scripts.pixelart_render.initand the camera frustum, view, projection, window size and clear buffers topixelart.scripts.pixelart_render.update. - outline (
selimanac/defold-3D-outline-shader, commit07c2eee) —import * as outline from "outline-shader.outline": a render script passes itsselftooutline.initand its predicates and a{ frustum }table tooutline.update, and a game script picks a stencil or inverted-hull outline withoutline.setandoutline.type. - sentinel (
indiesoftby/defold-sentinel, tag1.3.1, maintained here) —sentinel.initrequires adsn, sends itsusertable to Sentry as given, nested tables included, and takeson_soft_crashandon_hard_crashcallbacks that must return a string or a number, which the library writes into a log line.sentinel.capture_messagetakes one of Sentry's five levels. - GamePush (
megalanthus/defold-gamepush, tagv1.4.1, maintained here) —import * as gamepush from "gamepush.gamepush"reaches all 32 SDK modules through fields such asgamepush.playerandgamepush.platform, each also importable by its own id (import * as channels from "gamepush.core.channels"), and every module delivers its events to typed handler slots on itscallbackstable, such asgamepush.callbacksandgamepush.core.channels.callbacks. A table or argument the Lua rejects when missing is required, as forgamepush.initandgamepush.core.player.enable_auto_sync, and the Lua's constants keep their literal values, such asgamepush.languagesandgamepush.core.platform.YANDEX. - colyseus (
colyseus/colyseus-defold, tag0.18.1, maintained here) —import * as Colyseus from "colyseus.sdk"givescolyseus.Client, whose matchmaking calls take their options optionally and call back with either the error or the joined room,colyseus.callbacks, whose schema callbacks take the value type their callback declares, andcolyseus.protocolwith its literal codes. A room'sonaccepts only the six events it emits, each listener typed for its event. - printer (
Insality/defold-printer, tag1.2.2, maintained here) —printer.newreturns aprinter.Printerthat prints dialog text letter by letter in a gui scene, andprinter.printreturnsfalsewhen text was still printing and the new text did not start. Styles passed toprinter.add_stylescarry only the fields they change, copied over the style in effect or, for a source style, over the default style, except a style nameddefault, which replaces the default style and must carry its core fields. - ink (
abadonna/defold-ink, commit5e871c4, maintained here) —ink.createparses a compiled ink story into anink.Story, whoseink.Story.continueandink.Story.jumpreturn the paragraphs written and the answers to choose from, and whoseink.Story.get_stateresult restores the story throughink.Story.restore. - light_and_shadows (
Dragosha/defold-light-and-shadows, tagv0.9.1, maintained here) — a render script passes itsselftolight_and_shadows.light_and_shadows.initandlight_and_shadows.light_and_shadows.update, andlight_and_shadows.light_and_shadows.dofrequiresblur_resolutionin its options table, which the Lua copies with no fallback. light_and_shadows.light and light_and_shadows.constants type the light sources, camera position and shader constants a game script sets. - flow (
Pause-Games/flow, tag1.0.0) — requiringflow/flowgives the typedflow.flow.init,flow.flow.update,flow.flow.on_inputandflow.flow.on_messagelifecycle facade withflow.flow.ui,flow.flow.log,flow.flow.color,flow.flow.bottom_sheetandflow.flow.nav, whosereplacetakes a transition string and which carries the navigation message ids such asPUSH,on_messageand itshandle_messagealias both directly and undermessages; its page documents the component constructors inflow.flow.FlowComponents, the Markdown parse and viewer helpers inflow.flow.FlowMarkdownComponentand thenav.runtimemethods inflow.flow.FlowRuntimeFacade. The directly importable modules include flow.bottom_sheet, which type-checks its props, and flow.color, whose pages document calling the module itself (flow.bottom_sheet.FlowBottomSheetModule,flow.color.FlowColorModule), the chainableflow.flex.Node.new, and the shared element, style, screen and navigation types in flow.types. - pointer_lock (
indiesoftby/defold-pointer-lock, tag2.1.0, maintained here) —import * as pointer from "pointer_lock.pointer"givespointer_lock.transform_input, which returns the action id and theon_inputaction withxandymoved to the virtual cursor and its other fields kept, and returns no action id unless the pointer is locked and the cursor is visible.pointer_lock.lockedreads the lock state thatpointer_lock/pointer_lock.scriptkeeps. - operator (
astrochili/defold-operator, tag1.5.3, maintained here) —operator.operator.get_active_operatorreturns the active operator's url orundefined, and the settings fields, such asoperator.operator.flight_look_easing, are assigned through a cast. operator.bezier builds a curve withoperator.bezier.newfrom vector points, or from number points with a required length function, andoperator.bezier.Bezier.uniform_positionreturns the point that fraction of the way along it. - defarmy (
dev-masih/defarmy, tagv1, maintained here) —import * as defarmy from "defarmy.defarmy"givesdefarmy.army_createanddefarmy.army_update_pattern, which take one of thedefarmy.PATTERNhashes and, for theCUSTOMIZEDone, a function returning how many soldiers stand in each row.defarmy.soldier_movereturns a soldier's next position and rotation, bothundefinedonce the soldier is removed. - defgraph (
dev-masih/defgraph, tagV4.1, maintained here) —import * as defgraph from "defgraph.defgraph"builds a map withdefgraph.map_add_nodeanddefgraph.map_add_route, anddefgraph.move_playerreturns thedefgraph.MoveDatato keep beside adefgraph.MoveResultwhoserotationisundefinedunlessdefgraph.move_initializewas given an initial face vector. Every settingdefgraph.map_set_propertiesanddefgraph.debug_set_propertiestake is optional, anilkeeping its current value. - def_behavior_tree (
s-kania/def-behavior-tree, tag1.0.0, maintained here) —import * as BehaviorTree from "def_behavior_tree.behavior_tree"givesdef_behavior_tree.registerTemplates, whose templates take only their own node types and name a node by string only beside aNODEStable, anddef_behavior_tree.new, which types the tree and its task callbacks by the payload it is given,undefinedwhen there is none.def_behavior_tree.BehaviorTree.runstarts the tree at an optional node id and does nothing while it is running, anddef_behavior_tree.BehaviorTree.activeNodeisundefineduntil the first run. - dissolve_fx (
indiesoftby/defold-dissolve-fx, tag1.2.0, maintained here) —import * as dissolve_fx from "dissolve_fx.dissolve_fx"givesdissolve_fx.init, which takes an optionalstretchorcoverscale mode for the noise, anddissolve_fx.find_uvrect, which returns an atlas image's uv rect as four numbers. - illumination (
astrochili/defold-illumination, tag1.0.3, maintained here) —illumination.set_lighttakes a light whoseposition,color,radiusandcutoffare required, orundefinedto remove it, andillumination.set_environmenttakes any of its eight optional fields, its fog type one ofillumination.FOG_TYPE_NONE,illumination.FOG_TYPE_LINEARandillumination.FOG_TYPE_RADIAL. Theinitandpost_update_data_texturefunctions that only the bundledillumination.scriptcalls are not declared. - water (
selimanac/defold-stylized-water-shader, commitbdcc1d8, maintained here) —import * as water from "water.water"giveswater.init, which requires the camera, sun and water objects and the time speed, and getters such aswater.get_wave1that return their values as separate numbers. A render script callswater.render_initon the state itsinitreturns, after whichself.predicatesholds thewaterpredicatewater.render_updateneeds besidemodel, andwater.set_edge_foam_typetakes0or1. - defold-wrap (
baochungit/defold-wrap, tag1.1.0, maintained here) —import * as wrap from "wrap.wrap"giveswrap.wrap.nodeandwrap.wrap.go, which wrap a GUI node or game object as a wrap.node or wrap.go whosegui.*orgo.*setters chain, or a list of them as a wrap.node_list or wrap.go_list, andwrap.wrap.gui_applet, whose wrap.gui_applet shows wrap.gui_scene scenes made of wrap.gui_object objects. Each hook sees its scene or object asthis, in a subclass fromwrap.gui_scene.extendorwrap.gui_object.extend, which types its fields and an object's props and settings, or in a plain table of hooks and fields, which may not set the__name,newor__indexa class carries. - minit (
Minit-Games/minit-defold, tagv1.17.0, maintained here) —import * as minit from "minit.minit"givesminit.report_result, which takes a number or string score with optionalflavor_text,delayanduser_data, andminit.on_viewable_change, which returns the function that unsubscribes.minit.get_user_datareturnsundefinedwhen nothing is stored, and outside an HTML5 build every call prints or returns a fixed result. - asobi (
widgrensit/asobi-defold, tagv1.18.1, maintained here) —import * as asobi from "asobi.client"givesasobi.client.create, whose client carries its tokens, an asobi.realtime connection whoseasobi.realtime.Realtime.onaccepts only the 45 events it fires with each handler typed for its event, and the asobi.http transport and 15 REST modules such as asobi.api.auth, whose calls take the client first and call back with the decoded body or anasobi.http.HttpError.asobi.client.quick_startrequires ahost, andasobi.api.auth.guest_devicesigns a guest in with the device id and secretasobi.device.load_or_creategenerates and saves on first run.
- detiled (
- yagames declares the readiness flags its module table opens with:
yagames.ysdk_ready,yagames.payments_readyandyagames.player_readyreadtrueonceyagames.init,yagames.payments_initandyagames.player_initsucceed, andyagames.banner_readystaysfalse. - Fourteen more native extensions are typed by curated modules (Curated native extensions), each imported by its namespace (
import * as png from "png"), so a project depending on any of them gets types whereresolvewrote none:- def_windward_jps (
s-kania/def-windward-jps, tagv1.1.0) —def_windward_jps.create_gridreturns a grid whosedef_windward_jps.Grid.find_pathanddef_windward_jps.Grid.is_walkabletake 1-baseddef_windward_jps.Pointcells. - box2d (
d954mas/defold-box2d, tag1.0.3) —box2d.NewWorldreturns a world whose bodies, fixtures, shapes and joints carry their methods, andbox2d.World.CreateJointaccepts only the joint definitions the extension can build and returns the joint type each one names. - daabbcc3d (
selimanac/defold-daabbcc3d, tagv1.0.6) —daabbcc3d.insert_aabbanddaabbcc3d.query_aabbtake aVector3position with width, height and depth, anddaabbcc3d.rebuild_alltakes its flag second, where the runtime reads it. - wave (
selimanac/defold-wave, commit76ff0c9) —wave.add_gameobjectfloats a game object on the simulated water, andwave.get_wave1_heightandwave.get_wave2_heightrequire thetimeargument the runtime reads. - detour (
abadonna/defold-detour, commit95ce965) —detour.initloads a Recast navmesh whosedetour.NavMesh.find_pathreturns path corners keyed from 0, anddetour.NavMesh.create_crowdreturns adetour.Crowdthat steers agents along it. - taptic_engine (
MaratGilyazov/def_taptic_engine, tagv1.2) —taptic_engine.impact,taptic_engine.notificationandtaptic_engine.selectionplay haptics oncetaptic_engine.isSupportedconfirms the device can; the namespace exists on iOS only. - gyro (
britzl/defold-gyro, tag1.1.1) —gyro.starttakes a required listener the extension calls every frame with the device rotation as a quaternion, on iOS and Android only. - fontscale (
myopic-design/defold-fontscale, tagv0.1.0) —fontscale.getreturns the operating system's font-scale factor on every platform. - directories (
Lerg/extension-directories, commit2023870) —directories.path_for_fileresolves a file path inside the platform directory one of the five constants names, with both arguments optional, and returns nothing when the directory cannot be resolved. - uptime (
AGulev/defold-extension-uptime, tag1.2.0) —uptime.getreturns the seconds since the device booted, on iOS, Android, macOS and Windows only. - png (
britzl/defold-png, tag1.2.2) —png.encode_rgbandpng.encode_rgbaturn raw pixels into PNG bytes, andpng.decode_rgbandpng.decode_rgbadecode a valid PNG into a pixel buffer with its width and height, or three nils when the buffer cannot be created; a corrupt PNG may crash the engine.png.inforeads a PNG's dimensions, color type and bit depth without decoding it. - imp (
britzl/defold-imp, tag1.1.0) —imp.convolutionapplies a row-major 3x3 kernel to a source buffer and writes the result into a destination buffer; both need a uint8rgbstream and at leastwidth * heightelements, and the extension does not check the element count. - openal (
Lerg/extension-openal, commit618292f) —openal.new_sourcecreates anopenal.Sourcefrom a WAV file loaded withresource.load, or returns nil when it cannot load one, and the source's position, gain, looping and other properties are set in place beforeopenal.Source.play.openal.listeneris read-write,openal.doppler_factorandopenal.speed_of_soundare set through a local holding the import, and the extension needs Defold's own sound system disabled. - ainpc (
elefant-ai/player2-ai-npc-defold, commitecda39f) —ainpc.chat_completion,ainpc.npc_spawn,ainpc.npc_chatandainpc.npc_killsend requests to the running Player2 desktop app and require both a reply and a failure callback, andainpc.npc_responsesreturns the stream idainpc.stop_npc_responsestakes. A string body is accepted only where the extension reads it as one, and the docs note that agame_idreaches only theainpc.npc_responsesrequest.
- def_windward_jps (
Fixed
buildandwatchcompile a project using the types resolve installed (build): they load the declarations behind the tsconfig"extensions"andlibraries@<cliVersion>entries as type information only, where a curated native call such asuuid4.generatefailed withCannot find nameand a vendored library import such ascheckpoint.checkpointwithCannot find module.resolveworks from the published packages for a project depending on a native extension, under Node and Bun on macOS, Linux and Windows (resolve), where Node failed to load the types package's TypeScript scripts (a bareC:\path on Windows, type stripping undernode_moduleselsewhere) and Bun found none of thefixtures/defold-*documents in the published@defold-typescript/types. Reading an extension archive needs nounzipbinary and reads an archive carrying any comment that does not itself embed a zip directory.resolvekeeps every dependency's declarations of a namespace they share, writing each to its own.defold-types/extensions/<namespace>.<dependency>.d.ts, numbered when another file already has that name, and printingmerged <namespace> from <urls>(--jsonadds asharedNamespacesarray), where it kept only the last dependency's and a project using several Firebase extensions lostfirebasemembers (resolve). An extension declaring an engine namespace, such as Spine'sgui, no longer re-declaresgui.Playbackand 12 other engine type aliases, which a type check withskipLibCheck: falsereported as TS6200 conflicts.resolvekeeps both declarations when two namespaces differ only in letter case, such asFooandfoo, writing the second to a numbered file such as.defold-types/extensions/foo-2.d.ts, where on macOS and Windows one replaced the other (resolve).- druid, decore and proto methods take every parameter their Lua declares: one the LuaLS annotations leave out is an optional
unknown, sodruid.druid_layout.set_node_positiontakes itsis_instantflag andproto.Parser.addpathits path, where a call passing them failed withExpected 0 argumentsor one fewer. initandupgradewritenoEmit: trueintotsconfig.jsonwhen the project sets none, so a baretscno longer writes a.jsfile beside every.tssource;buildoutput is unchanged (init).
v0.53.0 - 2026-10-20
Summary:
- Engine type names are PascalCase on every Defold version, so rename them in your code, and enum slots follow the engine: anchor getters and setters share axis subsets, and animation and atlas playback accept all of
go.Playback.upgradecompares every version correctly, including prereleases.- Model texture properties include all sixteen slots.
- Debug launchers stay current through upgrades when unmodified, preserve and name customizations, support entry-script exports, and warn when F5 would run a stale engine build.
- API pages show the complete engine type inventory under one
Typesheading, with full paths, Defold-name links, fields and handle methods, as on socket.
Breaking
- Every type the engine declarations name is PascalCase and has one name on every Defold version, derived from the name the Defold reference gives it. Rename these in your code. A nested type renames only its last segment, and each type's row on the API pages links the reference's own name from its Lua badge, as on sys. A union the reference leaves unnamed keeps its alias, such as
render.ClearBufferKey, unless it is part of a named one in its namespace, which writes it asExcludeof that one.- Constant unions —
gui.EASING->gui.Easing,graphics.BLEND_EQUATION->graphics.BlendEquation,image.TYPE->image.Type,editor.ui.COLOR->editor.ui.Color. - Tables and component properties —
sys.sys_info->sys.SysInfo,go.on_input.action->go.on_input.Action,model.properties->model.Properties,gui.node_properties->gui.NodeProperties. - Handles and aliases —
gui.node->gui.Node,render.render_target->render.RenderTarget,b2d.b2Body->b2d.B2Body,bullet3d.btRigidBody->bullet3d.BtRigidBody,timer.timer_handle->timer.TimerHandle,physics.event->physics.Event,collectionproxy.TIME_STEP_MODE->collectionproxy.TimeStepMode,editor.command->editor.Command, andrender.render_target_params->render.RenderTargetParams, the name v0.52.0 already gave it on every version. - Names the rule cannot split —
gui.PIEBOUNDS->gui.PieBounds,crash.SYSFIELD->crash.SysField,crash.USERFIELD->crash.UserField,liveupdate.LIVEUPDATE->liveupdate.LiveUpdate,bullet3d.constraint.generic_6dof_params->bullet3d.constraint.Generic6DofParams. - Core globals —
vmath.vectorandresource.resource_dataare gone; writeVectorandHash. - socket —
socket.clientandsocket.socket_client->socket.SocketClient, and the same forsocket.SocketConnected,socket.SocketMaster,socket.SocketServerandsocket.SocketUnconnected. - go —
go.Playbackincludesgo.PLAYBACK_NONEon every target. - graphics —
graphics.Stateincludesgraphics.STATE_ALPHA_TEST_SUPPORTEDandgraphics.STATE_SCISSOR_TEST, whichrender.enable_stateandrender.disable_statereject, so those takeExclude<graphics.State, typeof graphics.STATE_ALPHA_TEST_SUPPORTED | typeof graphics.STATE_SCISSOR_TEST>; on Defold 1.13.2 and later,graphics.BufferTypetakesgraphics.BUFFER_TYPE_COLOR1_BITthroughgraphics.BUFFER_TYPE_COLOR3_BITonly once narrowed pastundefined. - gui —
gui.AdjustMode->gui.Adjust,gui.BlendMode->gui.Blend,gui.NodeType->gui.Type,gui.Property->gui.Prop, andgui.SafeAreaMode->gui.SafeArea;gui.get_xanchorandgui.set_xanchoruseExclude<gui.Anchor, typeof gui.ANCHOR_BOTTOM | typeof gui.ANCHOR_TOP>, andgui.get_yanchorandgui.set_yanchoruseExclude<gui.Anchor, typeof gui.ANCHOR_LEFT | typeof gui.ANCHOR_RIGHT>, on every target. - sys —
sys.NetworkConnectivity->sys.Network. - window —
window.DimModeState->window.Dimming,window.DimModeStateSettable->Exclude<window.Dimming, typeof window.DIMMING_UNKNOWN>.
- Constant unions —
Improved
- API pages file every type under one
Typesheading, named by its full path on engine pages, and every handle method underFunctions. An alias or interface is one row there, such asimage.Type, which opens with a Lua badge linking the reference's ownimage.TYPEto its defold.com entry, while a type with fields, such asgo.on_inputon go, and a handle's methods, such as theclientmethods on socket, each get a heading nested inside. - druid types follow
Insality/druid1.4.1:druid.druid_button.set_cursorsets one button's hover cursor, anddruid.druid_instance.reset_hoversclears every hover in an instance when another GUI covers it; both return their own object, so calls chain.
Fixed
go.animate,resource.create_atlas,resource.set_atlas, andresource.get_atlasuse the fullgo.Playbackunion on every target, includinggo.PLAYBACK_NONE.- An entry script wired by
setup-debugbuilds when it exports runtime values. The unedited managed block no longer fails the companion's order rule at itsif, and its gatedlldebugger.start()runs before the companion loads; an edited block is still rejected, with an error that says to rundefold-typescript setup-debugto restore it. - The F5 debug launcher carries a normalized body checksum and stays current through
upgradeorinit . --force. An unmodified current or legacy launcher is refreshed even after CRLF conversion, a customized launcher is preserved and named in a warning with an explicit reset path, and F5 stops for a missing engine build or warns before running a stale one. upgradereports the version the project had before the run — its installed@defold-typescript/cli, else itspackage.jsonpin — in the summary line and the--jsonfromfield, sobunx @defold-typescript/cli@latest upgradeno longer claims "already latest" after moving the project to a newer release. When neither names a version, the line readsnone -> <to>andfromis left out.upgradetells distinct prereleases apart — digit-led ones such as1.3.0-1alphaand1.3.0-1beta, and very long numeric ones such as1.3.0-9007199254740992and1.3.0-9007199254740993— so a CLI on the older one hands off to the newer one instead of re-scaffolding from its own templates and calling the project already latest.model.Propertiesdeclares all sixteen texture units the engine handles,"texture0"through"texture15", on every pre-baked Defold version, sogo.get<model.Properties>()("#model", "texture8")compiles; a surface generated from a reference doc alone keeps"texture0"through"texture7".- API reference pages list the complete engine type inventory, with every interface and type alias the declarations define shown in full. This covers the five socket handles and their methods (
socket.SocketClient,socket.SocketConnected,socket.SocketMaster,socket.SocketServer,socket.SocketUnconnected), option and result tables such asb2d.Aabb,bullet3d.VersionInfoandsys.SysInfo, and aliases such asgui.Node. - shutter and checkpoint point at their new home on Codeberg, where their author moved them after deleting the GitHub repos. Their reference pages and declaration source links lead there, and the adopt step gives the Codeberg archive URL to replace a dead
github.com/Klaleusdependency ingame.project.
v0.52.0 - 2026-10-17
Summary:
- GUI node properties are typed and material constants take
hash; the Box2D world queries take<"v3">to return v3 hits.- Declarations follow the engine bindings: optional arguments whose
nilraises rejectundefinedon pre-baked versions,goandguideclare no lifecycle hooks, resource markers compile only as property defaults in the one form Defold's build reads, render, Bullet3D, buffer and sound-data arguments,go.deleteand thego.getandgo.setoptions take only the values the engine accepts,material.get_texturesreturns a map keyed by sampler slot, andUrl.socketcan beundefined.- Script kinds keep only what they support:
propertiesisdefineScript-only, and render scripts lose what needs a game object.wall --checktype-checks walls, helpers they import included; re-runwall <dirs>to rewrite existing walls.- The build's own Lua moves to
lib/defold_typescript/, movable withruntime-dir, and state machine modules carry source maps; hand-authored Lua that requires the old root names must switch.
Breaking
gui.get,gui.setandgui.animatetake only the engine's node property names as strings, sub-keys included, or agui.PROP_*constant. Name a material constant or astring-typed name withhash(gui.set(node, hash("tint"), v)), set"rotation"with aQuaternion, and address the gui component withmsg.urlonly for"material","materials","fonts"and"textures", where"textures"withundefinedremoves the mapping on Defold 1.13.1 and later, the version from which the API reference andllms-full.txtlist that form; see GUI node properties are a closed set.- Optional arguments the engine raises on when passed
niltake a value or nothing on every pre-baked Defold version: each such function is declared once without the argument and once requiring it, so a value typedT | undefinedthere stops compiling; leave the argument out instead. A surface generated from reference docs keeps the reference's optional arguments, except ingo.get,go.set,gui.get,gui.setandgui.animate, which take a value or nothing on every version. The arguments are:- Options tables of
go.get,go.set,gui.get,gui.set,gui.play_flipbook,gui.stop_particlefx,sprite.play_flipbook,particlefx.stop,image.load,image.load_buffer,render.set_render_target,render.draw(Defold 1.13.0 and later),resource.get_text_metrics,sys.get_sys_infoandsys.open_url. delayofgui.animateandgo.animate, andflipofgui.new_textureandgui.set_texture_data.default_valueofsys.get_config_intandsys.get_config_number,recursiveofgo.delete,pathofgo.get_idandrequest_idofphysics.raycast_async.
- Options tables of
- Declarations and the build reject what the engine bindings raise on or ignore:
buffer.createandbuffer.set_metadatatake a list of at least one element, so pass a literal or type a list built at run time as[T, ...T[]];buffer.set_metadataalso rejectsbuffer.VALUE_TYPE_INT64andbuffer.VALUE_TYPE_UINT64.bullet3d.constraint.create_point_to_pointrequirespivot_b, andbullet3d.constraint.create_hinge,bullet3d.constraint.create_cone_twist,bullet3d.constraint.create_generic_6dofandbullet3d.constraint.create_sliderrequireframe_b_positionandframe_b_rotation, wheneverbody_bmay be a body. Passundefinedasbody_bfor a one-body constraint.bullet3d.constraint.get_slider_motorandbullet3d.constraint.set_slider_motortake amotorof"linear"or"angular".bullet3d.shape.definitionhas one arm per shapetype, each with the fields that shape reads, so a sphere withdimensions, a capsule withoutheightor a mesh does not compile.bullet3d.shape.get_shapecan also return a mesh's{ type }, so check a field such as"dimensions" in databefore passing the result back; comparingdata.typeto a constant does not narrow it (why).go.deletewithrecursivetakes an id or a list of ids, nevertrueorundefined;go.delete(true)alone deletes the calling object and its children.go.getandgo.settake an options table that names at most one ofindex,keyandkeys.material.get_texturesreturns aLuaMap<number, …>keyed by sampler slot from 1, since the engine leaves a slot with no texture out of the table: index it with.get(1)or iterate it withfor (const [slot, info] of textures)instead of[0]or.length.Matrix4columnsc0toc3read as aReadonly<Vector4>: a read is a copy, som.c0.x = 5does not compile, since it changes nothing. Assign a wholeVector4(m.c0 = v) to set a column.render.disable_texturerejects a texture handle: the engine reads any number as a texture unit, so a handle disables the wrong unit. Pass a unit number or a sampler name.render.enable_stateandrender.disable_statetake agraphics.State, the six states the engine accepts, sographics.STATE_SCISSOR_TESTandgraphics.STATE_ALPHA_TEST_SUPPORTEDdo not compile.render.render_targettakes atypeofrender.RenderTargetTextureType,graphics.TEXTURE_TYPE_2Dorgraphics.TEXTURE_TYPE_CUBE_MAP, on Defold 1.14.0, since any other texture type raises.render.set_blend_func_separatetakes agraphics.BlendFactor, one of thegraphics.BLEND_FACTOR_*constants, for each factor rather than any number.resource.create_sound_datarequiresfilesizewhenpartialistrue.Url.socketreads asHash | undefined: thesenderof an engine message posted with no sender, such asray_cast_responseorwindow_resized, has no socket, so check it before use; see A vector's size isv.length().vmath.dottakes two vectors of the same type, since aVector3paired with aVector4raises.- Buffers are typed
Opaque<"buffer"> & { length: LuaLengthMethod<number> }, so a value annotated as a bareOpaque<"buffer">does not pass to a buffer parameter; annotate it asReturnType<typeof buffer.create>instead. - Lifecycle hooks are not declared under
goorgui: the engine binds nogo.init,gui.updateor any other hook, so such a call raises. Type a standalone handler withScriptHooksorInputActioninstead oftypeof go.on_input; see Script lifecycle helpers. - Resource markers
resource.atlas,resource.buffer,resource.font,resource.material,resource.render_target,resource.textureandresource.tile_sourceare accepted only as adefineScriptpropertiesdefault whose Lua isresource.<kind>("<path>")with a string literal path, orresource.<kind>(), the one form Defold's build reads, so parentheses, type assertions and a literal key such as["material"]are accepted too. The engine binds no such function, so a call or a reference anywhere else,resource["material"]included, fails the build, as does a default reached through an alias, an optional call, or a key or path held in a variable; see Resource properties.
- Walls are standalone
tsconfig.jsonfiles the root config excludes but does not reference, sowall --checkreplacestsc -b --noEmitas the command that type-checks them. It checks each wall's program, the helpers it imports included, plus the root program; re-runwall <dirs>to rewrite walls an earlier release wrote, whichwall --checkreports until you do. - The build writes its own Lua to a runtime folder,
lib/defold_typescript/under the output root or the folderpackage.json"defold-typescript"."runtime-dir"names:lualib_bundle.lua,timers.luaandhsm/<module>.lualand there, the next build deletes the generated rootlualib_bundle.lua,defold_typescript_timers.luaanddefold_typescript_hsm/, andinitignores the new folder. Hand-authored Lua that requireslualib_bundle,defold_typescript_timersordefold_typescript_hsm.<module>must require the new path, such asrequire("lib.defold_typescript.lualib_bundle").
Improved
gui.getreturns each node property's type:"position"reads as aVector4,"rotation"as aQuaternion, and a sub-key or scalar as anumber, so a read needs no cast.- Each state machine module is written with a source map to the library's
.ts: a debugger frame inside the library opens TypeScript, andwatchandreloadconsole lines name that file when a local install keeps it inside the project. bullet3d.collision_object.is_rigid_bodynarrows its argument to a rigid body, so a checked collision object passes tobullet3d.rigid_body.apply_central_impulseand the other rigid-body functions without a cast.- API reference signatures bold only names: each signature heading, overview entry and overload form reads at normal weight with the member name, its parameter names and those of a function-typed parameter, property or return in bold, and the Parameters and Returns lists bold their slot names the same way while their labels and doc text carry no bold.
- The Box2D world queries take a
"v3"type argument on Defold 1.13.2 and later:b2d.world.cast_ray,b2d.world.cast_ray_closest,b2d.world.cast_shape,b2d.world.overlap_aabbandb2d.world.overlap_shapereturn the v3 hits and shape tables when called asb2d.world.cast_ray<"v3">(…), and the v2 ones with no type argument. The API reference andllms-full.txtlist both forms of each query as available from Defold 1.13.2, each with its own return type and description; see Box2D v3 query hits.
Fixed
- Declarations the engine bindings contradict follow the engine:
buffer.get_bytestakes just the buffer and is documented as returning every byte of it;stream_nameis optional and ignored.- Buffers have
buf.length(), which compiles to#bufand returns the element count. go.deletetakes any table whose values are ids, sogo.delete(ids)deletes everything acollectionfactory.createcall spawned.go.getof an array material constant withoutindexreturns every element, and the result casts toVector4[]in one step.gui.clone_treeandgui.get_treetakeundefinedfor the whole scene, but the argument cannot be left out, since a call without it raises; see Passing absence.hashtakes aHashand returns it unchanged, and the API reference andllms-full.txtlist both forms for every Defold version.http.requestpasses its response callback the sender url as a fourth argument.- Label and sprite vector properties take one sub-key per component: a
Vector3property (label and spritescaleandsize) takes.xto.zand a.xykey that is aVector3, and aVector4property (labelcolor,outlineandshadow; spriteslice) takes.xto.w. Sogo.get<label.properties>()("#label", "color.w")is anumber; see Component properties. liveupdate.LIVEUPDATE_NOT_INITIALIZEDis declared and is a member ofliveupdate.LIVEUPDATE, whichliveupdate.add_mountandliveupdate.remove_mountreturn while live update is disabled.material.get_samplersandcompute.get_samplersreport a sampler'stypeas agraphics.TEXTURE_TYPEor one of the values 6 to 10, which a separate sampler or texture binding reports and no constant names.msg.urltakes aHashor aUrlas its one argument, and its three-argument form takesundefinedforpathandfragmentas well assocket.render.render_predicateis theOpaque<"render_predicate">handlerender.predicatereturns, so a value annotated with it passes torender.draw.Url.sockettakesundefined, which clears the socket.
llms-full.txtdates each overload ofgo.get,go.set,go.property,render.render_targetandsys.get_config_stringby its own availability: their first form exists on every tracked version, so it carries no[through 1.13.1] [signature transition]tag.defineGuiScriptanddefineRenderScriptreject apropertiesblock: Defold buildsgo.propertyonly in.scriptfiles, so the field fails to compile and the transpiler refuses to emit the calls Defold's build would reject. A GUI or render script gets a per-object value from a siblingdefineScript, which declares the property and sends its value withmsg.postininit.- A partly walled project, and a wall that imports a helper from outside it, type-check: each wall checks a helper it imports against its own kind, and a helper no wall imports keeps the full surface; see Kind-neutral helpers.
- The
@defold-typescript/types/render-scriptentrypoint leaves out the functions that need a game object, which always raise "no instance could be found" in a render script: every function insprite,factory,collectionfactory,collectionproxy,label,model,particlefx,physicsandtilemap, most ofgo(go.get_position,go.animate,go.property), and part ofb2d,bullet3d,resourceandsound; see API availability by script kind. run,bob runand the debug launcher launch the native-extension build engine on macOS, where bob writes it tobuild/<arch>-osx/dmengine, and on every platform they stop with an error, rather than launch the stock engine, when the project has anext.manifestbut no build engine. Refresh an existing launcher by deleting.vscode/defold-debug.tsand runningsetup-debug.
v0.51.0 - 2026-10-14
Summary:
- Breaking: hooks and callbacks match what the engine calls and passes, and
render.render_target's table is typed.- Breaking: five engine returns can be
undefined, so narrow them before use, and ray-cast results carry norequest_idorgroup.- Breaking: a vector's size is
v.length()andurl.pathcan beundefined.- Reads and writes match the engine: component property catalogs declare its keys and the typed
go.set<P>()rejects the ones it never writes, id tables read by path, andUrlfields are writable.- Built-in messages and physics events match the engine: defaulted fields are optional, missing fields are declared, and
isPhysicsEventnarrows a listener event.
Breaking
- Hooks and callbacks match what the engine calls and passes:
window.set_listenerandcollectionproxy.loadcallbacks receive typed payload structs on Defold 1.13.2 and newer targets,window.event_dataandcollectionproxy.load_data. A callback that annotates either parameter as a record, or reads a key the engine never sends, stops compiling; drop the annotation or name the struct.defineRenderScriptaccepts onlyinit,update,on_messageandon_reload; a render script'sfinal,fixed_updateorlate_update, which the engine never calls, stops compiling.model.play_anim's completion callback receives nosender, so a callback declaring a fourth parameter stops compiling.isWindowEventnarrows a non-resize event'sdatatoRecord<string, never>, the empty table the engine passes, notundefined.
render.render_targetchecks its table on Defold 1.13.2 and newer targets, in both arities: each buffer needs aformat,widthandheight, and a format constant other than depth or stencil needs a nil check first. To build the table ahead of the call, type it asrender.RenderTargetParams, which every pinned target declares, as an open record on older pins.- Five engine returns can be
undefined, as the engine source shows:factory.createwhen the spawn fails,tilemap.get_tile,tilemap.get_tile_infoandtilemap.get_tilesfor an unknown layer (the first two also for a cell out of range), and the second value ofcollectionproxy.set_collectionwhen the change succeeds. Code that uses the result directly stops compiling; narrow it with!== undefinedfirst. - The typed
go.set<P>()form rejects keys the engine never writes:model.animationandsprite.texture0are read-only, so a typed write to either stops compiling. - Ray-cast results carry only what the engine sends:
physics.raycastresults have norequest_id, and on Defold 1.12.4 to 1.13.1 targets the result is one hit or a list of hits, as on newer ones; theray_cast_missedmessage has nogroup. Code that reads either field, or indexes the result without anArray.isArraycheck, stops compiling. - Three engine userdata types follow the metatables the engine registers:
vmath.vectorgives its size throughVector.length, called asv.length(), which compiles to#v; readingv.lengthas a field raises at runtime and stops compiling.Url.pathcan beundefined, since a socket-only address such asmsg.url("main:")has no path; check it before use.- An array constant read back from a constant buffer is a
ConstantArray, a 1-based proxy with nolength, not an array; assigning an array to it still compiles.
Improved
-
Urlfields are writable andMatrix4.multakes a number, as the engine allows: assignUrl.socket,Url.pathorUrl.fragmentaHashor a string, and scale a matrix withm.mul(2). -
More returned tables, property reads and callback payloads match what the engine source pushes:
graphics.adapter_limitsdeclaresmax_storage_buffers_per_stageon Defold 1.14.0 targets.sys.interface_infodeclaresfamily,"ipv4"or"ipv6", absent for any other interface, on Defold 1.13.2 and newer targets.go.getandgo.setread and write aMatrix4property, andgo.getreads"position.x"and every other single-component transform key as anumber, and"scale.xy"as aVector3.- Component property catalogs declare the keys the engine handles:
model.propertiesgainsmaterialandskin,physics.propertiesgainsbullet(Box2D only),mesh.propertiesgainsmaterialandtexture0throughtexture15, and newfactory.propertiesandcollectionfactory.propertiesdeclare a read-onlyprototype. - Id tables from
collectionfactory.create,gui.get_treeandgui.clone_treeread by path as well as by hash, as inids.get("/go"). on_inputtouch entries declare all twelve fields as always present, sotouch.xis anumberwith noundefinedcheck.http.requestresponses declareurl, andreport_progressevents declarebytes_sent.
-
Built-in messages declare what the engine handles and sends:
play_soundtakespanandspeed,play_animationtakesoffsetandplayback_rate,pause_soundandset_panare declared,collision_response,contact_point_responseandtrigger_responsecarrygroup, and theaandbbodies ofcontact_point_event,collision_eventandtrigger_eventdeclare the fields the engine sets. -
Physics listener events narrow with
isPhysicsEvent: on Defold 1.13.2 and newer targets eachphysics.set_event_listenerevent carries itstypehash, andisPhysicsEvent(event, "collision_event")narrows it to that one event.
Fixed
image.get_astc_headerreturns its header withoutundefined: the engine raises on invalid data instead of returning nil.sys.get_sys_inforeturnsdevice_model,manufacturer,device_identanduser_agentas strings: the engine always sets them, as an empty string where the platform has no value.- Built-in message payloads accept what the engine accepts:
set_gain'sgain,set_camera's orthographic fields,reboot's arguments andstart_record'sframe_periodandfpsare optional, andstop_soundtakes aplay_idto stop one voice.
v0.50.1 - 2026-10-13
Summary:
- Library types follow newer upstream tags for deftest, monarch and panthera.
Improved
- Three library types are checked against newer upstream tags, and their API reference pages name the new tag. The declarations are unchanged, so project code compiles as before.
- deftest is checked against
britzl/deftest2.9.0. - monarch.monarch, monarch.transitions.easings and monarch.transitions.gui are checked against
britzl/monarch6.0.3. - panthera is checked against
Insality/pantheraruntime.11.
- deftest is checked against
v0.50.0 - 2026-10-13
Summary:
- Defold 1.14.0 is the default API target (what changed), and its new APIs are typed.
- Pins built on demand are complete: channel and Defold 1.9.8 pins get all their types (pinning).
- The API reference keeps a saved version range and marks an outdated one in red.
Improved
- Defold 1.14.0 is the default API target, so a project that pins no target compiles against it, and code written against 1.13.2 compiles unchanged. Upgrading Defold versions lists the engine and project changes the compiler cannot check, and
--defold-target 1.13.2keeps the previous surface. - Defold 1.14.0 APIs are typed:
b2d.get_gameobject_idandbullet3d.get_gameobject_idreturn the game object that owns a physics body. A render script draws to one face of a cubemap render target with thefaceoption ofrender.set_render_target, thetypekey ofrender.render_targetand thegraphics.CUBEMAP_FACE_*constants. - The API reference flags a version range that stops short of the newest Defold release: the
Todropdown turns red while it shows an older version, so a range saved on an earlier visit stands out once a newer release is tracked.
Fixed
- Types on a channel pin — a project pinned to a channel whose release the toolchain builds on demand keeps the types one module declares for another, such as the
b2d.aabbthatb2d.fixture.get_aabbreturns, and functions documented under another module, such asbullet3d.collision_object.get_shapes. The types came out asunknownand the functions were missing; see Pinning the Defold target. - Defold 1.9.8 pin — a project whose pinned Defold target is Defold 1.9.8 gets its label declarations. The toolchain looked for that module's reference under the file name a later Defold release gives it, and found none.
- Saved version range in the API reference — the range picked in the
From/Todropdowns holds when you open the API from a guide page, move one end of the range there, or follow a link between API pages.Tojumped to the newest Defold release andFromwidened to the oldest, until the next guide page showed the saved range again.
v0.49.0 - 2026-10-12
Summary:
- A hand-built
MachineInstanceneedscan,onUnhandledandhasTagto compile.- Stricter types: a
whenthat assigns to a field ofctx, a callback that assigns to a field of its event, amachine.matches()in a hook given astringvariable or a path that names no state, a state built ahead of the config with a field no state has, and a path below a state with no child states all fail to compile.- State machines repeat code with
every, put rules on timers, group states with tags, wait for several engine calls withwaitGroup(), react to any event no state took with oneunhandledhook and resume a saved game from saved state paths.hsm-viewglowseveryruns, dims held timers, glows nothing for acancall and, attached to a running game, glows the rule eachinspectmove line names.- The state machines tutorial builds one robot buddy machine and a charging dock step by step, shows each change as a diff and covers every
hsmfeature.
Breaking
MachineInstancerequirescan,onUnhandledandhasTag: an object you build yourself and type asMachineInstance, such as a test double or a wrapper around a real instance, fails to compile until it has all three. In a wrapper, addcan: (event) => inner.can(event),onUnhandled: (listener) => inner.onUnhandled(listener)andhasTag: (tag) => inner.hasTag(tag); an instance returned bystartneeds no change; seeMachineInstance.- A
whenreadsctx, and every callback reads its event: an assignment to a field ofctxin awhenunderonoralwaysor in thedelayfunction of anafterlist, or to a field of the event in awhen, arunor anonMovelistener, fails to compile. Move the write intorun, copy a value out of the event before changing it, and type the parameter of a helper that takes a context class with a private member asReadonly<...>of the class; see Types. - A callback's
machinetakes the machine's paths: inside a hook, arunand atask,machine.matches()no longer takes anystring, so a path that names no state and a variable typedstringfail to compile there. Correct the path, or give the variable a union of the paths it can hold, such as"/menu" | "/play"; see Types. - A state takes only the fields of a state: a state built ahead of the config, in a constant or by a helper, fails to compile when it holds a field no state has, such as
label: "idle"besideenter. Remove the field, or keep it outside the state; see Types.
Improved
- State machines repeat code while a state is active, take rules on timers, name groups of states with tags, wait for several engine calls, react to the events no state took, resume a saved game, complete the paths a callback asks about, answer more about a running machine and show more in
hsm-view, the guide gains recipes and states each rule once, and the tutorial teaches every feature on one machine:every— a state runs code each time a delay passes while it is active, such as damage every half second or a rate of fire read from the context; a long frame runs it once, and a run is not a move; see Repeat while a state is active.- Rules on timers and
always— anaftertimer takesto,whenandrun, so a state can run code at a set time without leaving and a timer can wait for a condition once its delay has passed, and analwaysrule takesrun; see Rules on a timer. waitGroup()— ataskthat starts several engine calls waits for all of them: eachadd()returns the callback to pass, as inhttp.request(url, "GET", group.add()), andwaitruns its callback once every one has reported; seeWaitGroup.- A
whenreads the machine — a rule'swhenreceives the running machine as its last argument, read-only, so a rule can depend on the active states throughmatchesandhasTag, as inwhen: (_ctx, _event, machine) => machine.matches("/alive/posture/standing"); see Read another region in awhen. - Path checks —
machine.matches()inside a hook, awhen, arunand atasktakes only the machine's paths, the editor suggests them as you type, and a started instance fits a function that takesMachineInstance<Ctx, E>. A path below a state with no child states, andinitialorrestoreDepthon such a state, fail to compile where they are written; see Types. - Tags — a state lists
tags, andhasTagon the instance and on themachineevery callback receives answers whether any active state carries one, such as every state in which the player takes no damage; the names are the third type argument ofdefineMachine; see Name a group of states with tags. can(event)— returns whether a rule of an active state would take that one event, payload included, without moving the machine or running a hook; see Ask whether an event would be taken.unhandledhook — one hook on a state, or on the root, reacts to every event no state took, such as refusing any request by name; the event stays unhandled, socanstill answersfalsefor it; see React to an unhandled event.onUnhandled(listener)— calls the listener with each event no active state took, andinspectprints anunhandledline for it; see Listen for unhandled events.- Start position —
start(ctx, at)takes a list of state paths, such as a saved copy ofleaves, and enters those states through an ordinary entry; a path the machine lacks falls back to its closest parent, so a save made before an edit still loads; see Start at saved paths. hsm-view— the page glows aneveryentry that ran and the timer that fired, dims a timer itswhenholds back and glows nothing for acancall a hook makes; see Read the code. Attached to a running game, it glows the rule that made each move, which aninspectmove line names by its state and key, as in(OPEN: /closed, 0); see Attach to a running game.- Animation recipe — the guide builds one knight machine with looping animations, one-shots that finish before the next state, in-between animations between postures and a jump kept until it can play; see Animation states with one-shots.
- Waiting recipes — the guide shows how a state moves on once something has finished: a chain of child states, engine work counted with
waitGroup(), parallel regions joined by analwaysrule, and a group awaited in asequence; see Wait for something to finish. - Several machines recipes — the guide shows how two machines work together: machines on separate game objects that post messages to each other, two machines in one script where one reads the other, and a machine that runs only while a state of another is active; see Several machines.
- Shorter guide — the State machines guide states each rule once, in the section that owns it, and shows the few lines that carry each sample in place of whole scripts.
- One machine in the tutorial — State machines, one click at a time builds one robot buddy machine and a charging dock step by step, shows each change as a diff of the file you are writing, and covers every
hsmfeature. Live diagrams run the lessons up to save and load, send an event when you press its name, fill the names the machine takes right now, mark a name in every box that has it when you point at one and draw the buddy in its state and reacting to each event, and the later lessons run your own file inhsm-view.
Fixed
- Timer marks across a hot reload — in a state whose
afterlist reads a delay from the context, each timer keeps its own fired mark when a hot reload reorders the delays. A timer that had fired could fire again, and one that had not could be skipped; see What each instance keeps. hsm-viewon anafterlist — playing a machine whoseafteris a list glows the entry that fired. The first entry glowed whichever one fired; see Read the code.
v0.48.0 - 2026-10-09
Summary:
definePrivateMachineis removed; usedefineMachine.afterdelays can read the context.
Breaking
definePrivateMachineis removed:defineMachinetakes the optionalprivateCtxkey on its root config, so one function defines everyhsmmachine; see Private fields withprivateCtx. Rename eachdefinePrivateMachineimport and call todefineMachine; the config stays as written.
Improved
privateCtxtakes the starting context: the factory receives the object passed tostart, so a private field can start from a field ofCtx, as inprivateCtx: (ctx: TurretOptions) => ({ heat: ctx.startHeat }); see Private fields withprivateCtx. Givectxits type there; a factory with no parameter compiles unchanged.- An
afterdelay can read the context:afteralso takes a list such asafter: [{ delay: (ctx) => ctx.patrolFor, to: "/rest" }], whose delay is read once each time the state is entered, so one keyed machine serves instances with different delays; seeupdateandafter.
v0.47.0 - 2026-10-09
Summary:
- bridge moves to
v2.3.0: its social calls take a config entry id and reject a table.hsmgets private fields, andbuildreports type errors it crashed on.
Breaking
- bridge social calls take a config entry id: the library moves to
v2.3.0, wherebridge.social.share,bridge.social.invite_friendsandbridge.social.create_posttake the id of an entry inplaygama-bridge-config.jsonand reject a table, andbridge.social.join_communitytakes only its two callbacks. Replace a table argument with the entry's id, and drop theoptionsargument ofbridge.social.join_community.
Improved
hsmmachines keep private fields:definePrivateMachinetakes aprivateCtxfunction on the root config, and its fields reach every hook beside the context whilestartand the instance'sctxshow the context alone; see Private fields withdefinePrivateMachine.hsm-viewlists such a machine and shows the fields in its ctx panel.- bridge sends game events:
bridge.analytics.sendtakes an event name and an optionaldatatable.
Fixed
buildstops withundefined is not an objectinstead of a type error: some type errors on an object that holds an engine value such asmsg.url,hashorvmath.vector3, like an unknown field passed beside it, ended the build witherror: undefined is not an object (evaluating 'path.includes')and no file or line. The build now reports the error with its file, line and message.- A bridge platform message needed an
optionstable:bridge.platform.send_messageandbridge.platform.send_custom_messagefailed to compile withoutoptions, which the library lets you leave out. Both compile with the callbacks straight after the first argument.
v0.46.0 - 2026-10-07
Summary:
hsmgains a cheat sheet and hover docs;hsm-viewtakes the docs site's look, shows icons on its controls, reads object literals, marks a field it cannot read, opens it in a dialog and logs every failed action.- A script that exports an
hsmmachine loads in the game.
Improved
hsmdocuments itself in the editor: every config key, everyMachineInstancemember and every export of the fourhsmmodules shows what it does on hover and beside each completion; see Reference.hsm-viewhas a new look, icons on its controls, fields that check what you type and open in a dialog, and a log line for every failed action; see Run the machine:- Look — the page uses the docs site's palette in light and dark, and its buttons, fields, dropdowns, layout toggle and log checkboxes show hover, focus and disabled states on a muted bar.
- Icons —
Start,Play,Pause,Stepand the layout toggle'sListandStackedeach draw an icon before the label, and the ctx tree's expand and collapse arrows are icons. - Fields — the starting context and the event payload take a TypeScript object literal such as
{ enter: true, from: 'pad' }as well as JSON, and a field that cannot be read is outlined in red while you type, with a message that names where the mistake is. A button beside each field opens its text in a dialog with a multi-line editor, whereStartorApplywrites it back. - Errors — every failed action adds an error line to the log, and one that belongs to no field also shows in a popup that closes by itself. The banner under the bar shows what still holds, such as a lost connection or a halted machine; see Errors.
- The State machines guide has a cheat sheet: three tables pair a task with its solution and a snippet to copy, covering each common state config part, the instance, context, event and path types read off the machine with
typeofandReturnType, and five ways to typeself; see Cheat sheet. New sections show how to restart a machine and how a restart works with hot reload.
Fixed
- A script that exports an
hsmmachine no longer stops the game: the Lua module written beside a script for its exports required thehsmor timers module by a path Defold cannot load, so the game failed withcould not be found, or with anInvalidPathExceptionon Windows. It now requires the module the way the script does; see Exporting a value from a script itself.
v0.45.0 - 2026-10-06
Summary:
hsmpath errors land on the mistyped property, with editor suggestions.- Breaking:
hsmupdatehooks return a machine path, not a plainstring.- Reference examples make every call their Lua sample makes.
Breaking
hsmupdatehooks return a machine path: anupdatehook that returns a plainstringno longer compiles. Return one of the machine's full paths orundefined, and addas constto a hook declared outside the config (() => "/grounded" as const). TheMachineConfigErrorandDefinedMachinetypes are removed, becausedefineMachinereturns aMachinefor every config that compiles; see Types.
Improved
hsmreports a bad path where it is written: a mistypedinitial,to,after,alwaysorupdatepath, or anonkey that names no event, is a compile error on that property instead of on the laterstartcall. The editor suggests the machine's paths and event types as you type; see Types.- Examples show their whole Lua sample with the declared types: the API-reference and hover examples for the material functions,
compute.set_constants,compute.set_textures,b2d.fixture.set_shapeandb2d.shape.set_shapemake every call their Lua sample makes, script properties and comments included. The callback examples forgui.play_particlefx,particlefx.play,sys.set_error_handlerandwindow.set_listenerpass their callback inline, so each parameter takes its declared type instead of anunknownannotation, as the callback gotcha describes.
Fixed
model.get_blend_weightsexample sets the wrong weights: the example wrote the second and third weights where its Lua sample writes the first two; it now writesw[0]andw[1].
v0.44.1 - 2026-10-05
Summary:
hsm-viewshows its page again.
Fixed
hsm-viewopens to a blank page: the browser page failed as soon as it loaded, withT is not a functionin the browser console, so no machine, source or controls appeared. The page now loads and shows the machine picker, your source and the controls.
v0.44.0 - 2026-10-05
Summary:
hsmnames read as sentences: rules gotoa statewhena check passes andruncode, and a state'staskreplacesinvoke.- Self-targets restart: a
tonaming the rule's own state exits and re-enters it, replacingreenter.hsm-viewruns a state-machine file in your browser, with live reload on save, and follows a running game.hsmstate flow gains cancellable sequences, restore on entry,alwaysandparallelregions.hsmhot reload reaches running machines, and an inspector logs each move.
Breaking
hsmkeys and types are renamed: the transition keystarget,guardandactionsareto,whenandrun, a state'sinvokeistask, and the typesInvokeStartandTransitionActionareTaskStartandMoveAction; an old key fails to compile, inonandalwaysrules alike, and hovering it names its replacement. Ataskmay return a cleanup, so brace an expression body that returns anything but a function, such as(_ctx, finish) => timer.delay(...); see Events and transitions and Engine callbacks.hsmreenteris gone and a self-target restarts: atonaming the state the rule is on exits and re-enters that state, restarting its timers andtask, where it used to keep the state and restart only its children; a self-targetingafterrepeats. Writereenter: trueas the plain path, and restart only the children by naming the child to start in; see Events and transitions.hsmmessage events carry the sender:messageEvents(...).toEventtakes theon_messagesenderas a required third argument, and everyMessageEventhas anevent.senderthatwhenandruncan reply to. Passsenderto eachtoEventcall and add it to anyMessageEventyou build by hand; see The message bridge.hsminstances gainonMoveandleaves:MachineInstancehas requiredonMoveandleavesmembers, so add or forward both on any object you build as aMachineInstance(a test mock, a proxy). Where a parameter typedMachineInstance<Ctx, E>receives an instance with more event types, widen itsEto the machine's full event union; see Debug a machine.
Improved
hsm-viewruns a state machine in your browser:bunx @defold-typescript/cli hsm-view <file> [name]serves a local page that runs the machine from source, tints its active states in the code, glows each rule that fires and, more dimly, eachonentry whosewhenturned the event away, and lets you send events, play or step time, edit its ctx and read a log, reloading live on every save; see hsm-view. It can also attach to a game launched from the editor and tint the states of aninspected instance as the game moves it; see Attach to a running game.hsmmachines are easier to script, resume, branch, split into regions, debug, reload and budget:- Scripted sequences — a
taskmay return a cleanup the machine runs on every way out of the state, andsequence(async (ctx, signal) => ...)from@defold-typescript/types/hsm/asyncbuilds one whoseawait signal.wait(seconds)never resumes after the state is left. Any otherawaitin a sequence can resume after the state is left, so checksignal.abortedafter it; see Scripted sequences. - Restore on entry —
restoreDepthon a compound state enters the children that were active when it was last left instead ofinitial, that many levels down or every level with"all", and a parallel state does not count as a level. The memory is per instance and survives a hot reload, while a target inside the state still lands where it names; see Resume with history. alwaystransitions —alwayson a state lists targets taken right after any move that leaves it active, deepest state first, the first passingwhen(ctx)winning, reported toonMovewith the cause"always"; an 11thalwaysmove in a row throws instead of looping. See Move on at once withalways.- Parallel regions — a state with
type: "parallel"keeps every child active at once, ordered by child name in Unicode code point order, each region taking its own events,updateticks,aftertimers andalwaysmoves, while an event no region takes bubbles above it.leaveslists every active leaf,pathstays the first, and the inspector draws them all; see Run regions side by side withparallel. - Debug inspector —
onMove(listener)on a machine instance calls the listener after each move with the old and new state path, the cause and the event, and returns a function that removes it.inspect(instance, label)from@defold-typescript/types/hsm/debuguses it, in debug builds only, to log the starting state and each move with every active leaf, backslash-escaping brackets, parentheses, commas and colons inside a logged name, and to draw those leaves over a game object, giving a repeated label the next unused ordinal (enemy#2); see Debug a machine. - Hot reload — a definition made with
defineMachine<Ctx, E>("key")reaches running instances on their nextsendorupdateafter a reload, with noon_reload: kept states keep their context and timers, and a removed state falls back to its surviving parent'sinitial, reported toonMovewith the cause"reload". See Hot reload. - Performance — 200 objects each running a three-level machine cost about 0.05 ms per frame in the stock engine, and
updateandsendbuild no tables. Performance records the numbers and shows how to hoist constant events off a hot path.
- Scripted sequences — a
Fixed
- Strict installs load the transpiler:
@defold-typescript/transpilerdeclarestypescript, so an install with strict dependency resolution (pnpm, Bun's isolated linker) no longer fails to load it. hsmaftertimers on a parent no longer fire late: when anupdatehook transitioned one of its children, the parent missed that call'sdt, so its timer fired one tick late per such transition. Every active state now counts thedtof everyupdatecall, as the State machines guide describes; a timer due on the same tick a hook transitions still waits for the next call.- The State machines tutorial no longer jumps in Safari: the live diagrams on State machines, one click at a time pulled the page back while you scrolled, pinning it short of the bottom. They now redraw only what changed, and a diagram scrolled out of view pauses until you scroll back to it.
- Four declarations match what Defold accepts and returns:
go.setandgo.gettake and return astring, the value of a text property (Defold 1.13.2 or later).b2d.body.get_transformandb2d.body.get_mass_datadeclare only the table they return, without an opaque-handle overload.zip.packtakes its entries as a list; a bare path string, which the editor rejects, is a compile error.http.server.routeaccepts an OpenAPI table right after the path or after the method.
v0.43.0 - 2026-10-02
Summary:
- New typed
hsmstate machine library: import it from@defold-typescript/types/hsm.- Two new guides: the State machines guide and a beginner tutorial with live diagrams.
Improved
hsm, a typed hierarchical state machine library, ships with the toolchain:import { defineMachine } from "@defold-typescript/types/hsm"andimport { messageEvents } from "@defold-typescript/types/hsm/defold"type-check in the editor and the build, which writes only the modules your code uses todefold_typescript_hsm/under the output root, with no source map; machines type their events, context and state paths, every target,initial,pathandmatches()uses one full path from the root such as/on/dim, a stopped machine'spathisundefined, and an unknown or relative target, a badinitial, a state name containing/or anafterkey that is not a non-negative number fails at definition with the same message in Defold as in TypeScript, the path mistakes at compile time too. The State machines guide covers the model first (transitions, timers, run-to-completion), then one instance per object onself, the message bridge, engine callbacks, a walkthrough that migrates the platformer example's player and a reference table, and every sample on it compiles against the shipped declarations.- State machines, one click at a time joins the tutorials for readers who have never used a state machine: eleven short parts, from a two-state lamp to timers, waiting on work and wiring a machine into a script, with eight live diagrams that run the real
hsmlibrary and samples that all compile against the shipped declarations.
v0.42.0 - 2026-10-02
Summary:
buildandwatchdrive the open Defold 1.13.2+ editor: they compile your project there or build and launch the game, and report each issue at its TypeScript line.- The API reference shows each function's history across Defold releases as it applies: overloads added or removed in a release are summarized, and a changed signature reads as one function with its earlier form below it.
- API search hits open the exact member they matched.
Improved
build --editor-compile,build --editor-runandwatch --editor-compiledrive the open Defold 1.13.2+ editor:buildcompiles the project or builds and launches the game once the Lua is written, printing the engine's URL (--editor-focusbrings its window forward) and exiting1on failure, whilewatchcompiles after every successful build and project file change, keeps running on a failed compile, and ships as thedefold-typescript:watch-ecanddefold-typescript:watch-hr-ecmise tasks. Each issue shows at its TypeScript line,--jsoncarries the result aseditorCompileoreditorRun(oneeditorCompileevent per compile underwatch), an older or missing editor is reported in one line without failing, and every other command rejects the flags; see Compile in the editor, Run in the editor and watch.- Overloaded functions whose forms span different Defold releases open with a summary in the API reference, such as "1 overload added in Defold 1.13.2" on
go.property, and a form dropped in a release shows below the forms as a "Removed in Defold …" line led by aCchip.
Fixed
- The API reference shows each function's history as it applies:
go.propertyforms — thego.property(name: string, value: string)form reads "Since Defold 1.13.2" instead of showing as available on every version, while the othergo.propertyforms keep their full span and the function's heading reads Changed.- Signature changes — a function whose signature changed between Defold releases, such as
b2d.get_worldorjson.decode, renders under its current signature with a "Signature changed in Defold 1.13.2 — before: …" line led by aCchip, instead of listing the replaced form as a second overload. - One score per function — a function whose signature changed between Defold releases, such as
json.decode,go.getorgui.set, reads Changed on its heading and counts once as changed in the namespace title and sidebar pills, rather than also as new. - "On this page" outline — an entry and its hover tooltip show the heading's colored
N/C/D/G/Uchips instead of plain trailing letters, and hide a chip the version window hides; the tooltip shows the3 overloadspill in the signature's code font instead of....
- API search hits open the member they matched. Searching
get_positionlistsgo.get_positionby name, and clicking a hit in the search box or on the search page scrolls to that member's heading instead of the top of the go page; types and their fields land the same way, such asb2d.joint.JOINT_TYPEormonarch.monarch.ShowOptions.no_stack.
v0.41.0 - 2026-09-30
Summary:
- Defold 1.13.2 is the default API target (what changed), and its new APIs are typed, including the bullet3d physics namespaces and text script properties.
- The breaking changes catch at compile time what used to fail when the script ran: a missing required argument or table field, a call the engine's Lua bindings reject, or a value typed differently from what the engine returns;
options.indexis also 1-based again.- Declarations stricter than the engine are relaxed, curried
go.get<P>()andgo.set<P>()calls reach the engine, andreloadandwatch --hot-reloadwork against a 1.13.2 editor.- Hovers and the API reference state the base of every index and show each example as its own TypeScript block with the engine's Lua sample beside it.
Breaking
- Defold 1.13.2 is the default API target, so a project that pins no target compiles against it:
b2d.get_world,b2d.body.get_nameandb2d.body.get_nextmay returnundefined,json.decodereturnsunknown, and the LuaSocket address and statistics getters return several values. Upgrading Defold versions lists every change, and--defold-target 1.13.1keeps the previous surface. - Calls the engine's own Lua bindings reject no longer compile. Each form below compiled before and raised when the script ran; the type error now points at the spelling that works.
- Required arguments:
- Factories and proxies —
factory.get_status,factory.load,factory.unload,factory.set_prototype,collectionfactory.get_status,collectionfactory.load,collectionfactory.unloadandcollectionfactory.set_prototypeneed the component url, andfactory.loadandcollectionfactory.loadtheir completion callback;collectionproxy.set_collectionneeds its url. - Values, tables and callbacks —
sound.set_gainandsound.set_panneed the value;resource.create_bufferandresource.create_sound_dataneed their table;resource.create_texture_asyncneeds its callback; andsys.set_engine_throttleneedscooldownunlessenableisfalse.
- Factories and proxies —
- Required table fields — the texture tables of
resource.create_texture,resource.create_texture_asyncandresource.set_textureneedtype,format,widthandheight; atlas tables needtexture, at least one geometry and one animation, per animation itsid,widthandheightplus a non-emptyframeslist or bothframe_startandframe_end, and perresource.set_atlasgeometry itsvertices,uvsandindices;resource.create_bufferneedsbuffer,resource.create_sound_dataneedsdata, and eachbuffer.createstream needstype. Box2D mass data, fixture filters, mover capsules andb2d.world.overlap_aabbbounds need every field, and theb2d.body.create_chainandb2d.world.explodedefinitions, which took any table, are typed with their required fields. - Shape tables are one form per
type— Box2D shape tables take ab2d.shape.SHAPE_TYPE_*constant and thephysics.set_shapetable aphysics.SHAPE_TYPE_*one, each plus that kind's fields, such as{ type: b2d.shape.SHAPE_TYPE_CIRCLE, radius: 8 }; rebuild a table read fromphysics.get_shape,b2d.fixture.get_shapeorb2d.shape.get_shapethat way before setting it again.b2d.world.cast_shapeandb2d.world.overlap_shapeaccept every kind, and the engine raises on one its backend lacks: capsule and segment on v2, chain on v3. Every other Box2D function takes only its backend's kinds:- v2 —
b2d.body.create_fixtureandb2d.fixture.set_shapetake box, polygon, circle, edge and chain. - v3 —
b2d.body.create_shapeandb2d.shape.set_shapetake box, polygon, circle, capsule and segment, andb2d.body.create_shapetakesis_sensororsensor.
- v2 —
- Table forms only —
b2d.body.create_fixtureandb2d.body.set_mass_datatake their definition table; the forms taking anOpaque<"b2Shape">or anOpaque<"b2MassData">are gone from the declarations and the API reference. - Render predicates are a handle —
render.predicatereturnsOpaque<"render_predicate">, andrender.drawtakes that instead of a number. - Pass
undefinedrather than leaving the argument out — the binding reads it even when absent:gui.move_aboveandgui.move_belowtakereference,gui.set_parenttakesparentandgui.settakesvalue,factory.set_prototype,collectionfactory.set_prototypeandcollectionproxy.set_collectiontakeprototype, andwindow.set_listenerandhtml5.set_interaction_listenertake the callback. Writegui.move_above(node, undefined)orwindow.set_listener(undefined). - Narrower types —
sound.get_group_nametakes a hash,model.get_mesh_enabledandmodel.set_mesh_enabledtake the mesh id as a string or hash,resource.create_texture_asynctakes its path as a string, theset_cameramessage takesorthographic_projectionas a number, andlabel.scaletakes aVector3, sincego.setrefuses a number (go.animatetakes one). - Read-only properties —
go.set<P>()accepts only writable keys, and the properties the reference marks READ ONLY arereadonly:sprite.animation,sprite.frame_count,camera.orthographic_auto_zoom,camera.projection,camera.viewandphysics.mass. This and thelabel.scalenarrowing apply togo.set<P>(), which reaches the engine this release;go.set(url, key, value)without a type argument is unchanged. sys.set_render_enableissys.set_render_enabled, the name the engine registers; the documented name isnilat runtime.- Functions no binding registers are gone —
b2d.body.get_user_data,b2d.body.set_user_dataandb2d.body.get_contact_liston Defold 1.13, andb2d.body.reset_mass_dataon 1.12.4.
- Required arguments:
options.indexatgo.get/go.setandgui.get/gui.setis 1-based again and passes to Defold unchanged, as Defold documents: add 1 to eachindexyou wrote for v0.40.0. An options variable, a spread and anindexthat may beundefinednow compile. See Engine array properties.- Types that match the engine — values the engine hands back are typed as what it actually returns:
- Return values — code that assumed a value is always there needs a check:
sys.get_config_stringreturnsstring | undefinedunless you pass a default,b2d.world.cast_ray_closestcalled with afilterandb2d.shape.ray_castreturnundefinedon a miss, andgui.new_texture's error code isundefinedon success.b2d.body.get_world_centerreturns avmath.vector3, never anumber, andcollectionproxy.get_resourcesreturnsstring[], the hexadecimal resource ids the engine pushes, notHash[]. go.scalereads arenumber | Vector3, and the engine always returns avmath.vector3: narrow the result, or readgo.get_scale()for aVector3. Writes also take a number as a uniform scale.- String constants —
gui.PROP_*andimage.TYPE_*are the strings the engine registers; stop using them as numbers. render.RENDER_TARGET_DEFAULTisundefined, thenilthe engine reads since it never registers the constant; stop using it as a number.render.set_render_target(render.RENDER_TARGET_DEFAULT)still selects the default target.- Input actions —
acc_x,acc_yandacc_zare fields of theon_inputaction, not of each touch; touches carryscreen_x,screen_y,screen_dxandscreen_dy;gamepadhatsisgamepad_hats; andmarked_text, which the engine never sends, is gone.
- Return values — code that assumed a value is always there needs a check:
- A druid slider's style is typed:
druid.druid_slider.styleisdruid_slider_stylerather than a plainLuaTable, so a value declaredLuaTableno longer assigns to it; read and write its fields directly, such asdruid.druid_slider_style.DEFAULT_STEPS.
Improved
- Defold 1.13.2 APIs are typed: the bullet3d 3D physics namespaces,
label.get_layout_objectsandgui.get_layout_objects, theproxy_loading,proxy_ready,proxy_errorandtext_object_*messages, andwindow.WINDOW_EVENT_ICONIFIED, whichisWindowEventandwindow.set_listeneraccept. Tables the 1.13.2 reference names, such asimage.load_result, are named types, and the constants it newly documents,render.CONTEXT_EVENT_CONTEXT_LOSTandrender.CONTEXT_EVENT_CONTEXT_RESTORED, have entries on its API reference page. - Text script properties on Defold 1.13.2: a string default in
defineScript({ properties })registers a text property typedstringonself, a deprecated directgo.property("greeting", "Hello")compiles too, and on an older targetbuildandwatchrefuse any script declaring a property of either form that may hold a string, naming the property and both versions.label.propertiesdeclares a writabletext, sogo.get<label.properties>()("#label", "text")reads a label's text. editor.platformis typed as the four platform ids it can hold, soeditor.bob({ platform: editor.platform })compiles as the reference writes it.- Every engine index states its native base in hovers and the API reference as one bold sentence led by a marker, "⚠️ 1-based; passed to Defold unchanged." or "0️⃣ 0-based; passed to Defold unchanged.", on the slot itself or naming the table field it covers, including bases the reference states only in a function's notes or description: the geometry
indicesofresource.create_atlas,resource.set_atlasandresource.get_atlas, and themipmapofresource.set_texture; the editor-scriptimage.pixelsmarks the base of its coordinates the same way. The guide's Engine indexes use Defold's base lists every such position by base in a table built from the same data, so it names exactly the positions the hovers mark. - Library and extension indexes state their base the same way, naming the library, as in "⚠️ 1-based; passed to
gooeyunchanged.": the API reference notes it on parameters, returns, each value of a multi-value return that holds a position (tile_x,tile_yandarray_idfromtile_raycast.cast), table fields, callback arguments and class fields of every library that takes or returns a position. Editor hovers show the same note for every library declaration, such as bridge, druid, gooey and tile_raycast, and for each extension resolve types from a curated page, such as steam and spine. - API symbol names in the guide and changelog link to their reference entry: inline code such as
go.get,render.RENDER_TARGET_DEFAULT, the global functionhashor the global typeVector3opens that entry in the API reference. - Every function with several examples documents each one as its own TypeScript block, with the sentence that introduces it above, in hovers and the API reference: among them
gui.set,render.draw,sys.load_buffer,json.decodeandeditor.bob, each of which showed one welded block. The API reference does the same forgo.getandgo.set, including their named-property and sub-component cases. - Every TypeScript example in the API reference has a Lua tab beside it showing the engine's original sample, in function examples and in code samples inside descriptions and parameter docs; the selected tab's badge is highlighted.
- The ten
in.*library types are checked againstbritzl/defold-input4.8.0, and their API reference pages name that tag; the declarations are unchanged. - Library parameters typed as string-keyed tables accept an object literal as well as a
LuaTable, such as thecomponentsofdecore.createand thenodesofpanthera.create_gui; tables a library returns stayLuaTable. - druid types follow
Insality/druid1.4.0: the button, drag, scroll, input and slider styles take optional hover cursors, such asdruid.druid_button_style.ON_HOVER_CURSOR, a slider exposes itsdruid.druid_slider.hovercomponent, and rich text word metrics reportdruid.druid_rich_text_metrics.visible_width. - Overloaded functions in the API reference lead with their description: the shared description and its warning sit above the forms and the shared example follows the parameter tables, so
go.propertyreads as one description followed by its eight forms, and its description, in hovers too, states that astringdefault needs Defold 1.13.2.
Fixed
- Declarations stricter than the engine's own Lua bindings accept what the engine takes:
- Optional arguments —
go.world_to_local_position,go.world_to_local_transformandgo.cancel_animationsmay leave out the url to act on the calling object,render.set_render_targetwith no argument restores the default target,vmath.vectorwith no argument makes an empty vector, andb2d.fixture.set_densitymay leave outupdate_mass. - Wider types:
- Camera and group ids — every camera function takes the camera as a url string or a hash, and so does
render.set_camera;physics.set_group,physics.get_maskbitandphysics.set_maskbittake the group as a hash;collectionproxy.get_resourcestakes the proxy as a url string or a hash; andresource.get_text_metricstakes the font path as a string. - Vectors, matrices and hashes —
gui.screen_to_localandgui.set_screen_positiontake avmath.vector4;particlefx.set_constanttakes avmath.matrix4; andgui.animateandgui.cancel_animationstake the property as a hash.
- Camera and group ids — every camera function takes the camera as a url string or a hash, and so does
- Return values —
sys.saveandtilemap.set_tilereturn a boolean,b2d.body.create_shapereturns the created shape'sindex,shape_id,typeand material fields, andb2d.shape.get_shapereturns a capsule'scenter1andcenter2. - Table fields — the
gui.getoptions takekeyandkeysand thegui.setoptions takekeys,b2d.body.create_fixturetakesis_sensor,resource.create_sound_datatakes a buffer asdata, eachresource.create_atlasgeometry takesvertices,uvsandindices, each atlas animation takes aframeslist, and Box2D shape tables take a capsule'scenter1andcenter2. - Constants —
graphics.DATA_TYPE_*,graphics.COORDINATE_SPACE_*andmaterial.CONSTANT_TYPE_*on Defold 1.13, andrender.TEXTURE_BIT, are declared; the engine defines them, and the reference names them only in prose.
- Optional arguments —
- Curried property access reaches the engine —
go.get<sprite.properties>()("#sprite", "animation")and the matchinggo.set<P>()form compiled to an emptygo.get()call that raised in the engine; they now callgo.getandgo.setdirectly. - API reference pages agree with their declarations: each parameter row marks a slot optional exactly when the signature above it does (every camera getter's
camera,b2d.joint.create_*'sdefinition), a slot doc that lists constants keeps them under its own bullet, and a version's search results show the same signatures as that version's pages. - Hovers and the API reference keep the layout of upstream docs: the tile grid of
tilemap.set_tileis fenced with its spacing, code samples such as those ofphysics.get_shape,physics.set_shape,physics.set_group,physics.wakeup,resource.create_textureandresource.create_texture_asyncshow as fenced TypeScript in hovers and the reference, andrender.render_target's in the reference, the result tables ofsocket.dns.getaddrinfoandsocket.dns.getnameinfoshow as fenced Lua, nested lists such as thetypeconstants ofimage.loadstay nested, list items sit on consecutive lines, and thegraphics.get_adapter_inforeturn lists each field on its own line with thelimitsandfeaturesentries nested beneath. reloadandwatch --hot-reloadwork against a Defold 1.13.2 editor, which they reported as absent although it had reloaded the game. A reload the editor rejects now fails with its issues, printed on stderr and listed undereditorIssuesin--json; older editors behave as before. See reload.
v0.40.0 - 2026-09-26
Breaking
options.indexis 0-based atgo.get/go.setandgui.get/gui.set:{ index: 0 }now addresses the first element of an array property, and the transpiler emits Defold's 1-based value. Subtract 1 from every existingindexat these calls; see Engine array properties.
Improved
- Vectors and rotations is a new tutorial on the math behind movement — positions, vectors, speed, dt, rotation, the dot product and local versus world space, one game problem per lesson, ending with a ship that drifts through space. Its fifteen figures follow the site font and the light/dark theme and stack their side-by-side panels on a phone, and every TypeScript snippet on the page type-checks against the shipped declarations.
- bridge moves from
v2.1.0tov2.2.0, addingplatform.launch_source,platform.dataand the post-reward pairsocial.is_post_reward_supported/social.get_post_reward.share,invite_friendsandcreate_postalso accept a config-entry id asoptions, andcreate_posttakes an optionalpayloadstring before its callbacks; every existing call still compiles. - An overloaded function in the API reference renders as one block, such as
msg.url: its heading readsname(N overloads)with a teal count badge plus the return type every form shares, the syntax-colored call forms come ahead of any toolchain note like the one ongo.property, and each fact the forms share is stated once while each form keeps its own description, example, parameters and returns, as onvmath.lerp. Forms that are one function's signature across Defold releases, such asgui.set, show only the newest example; the function overview and the "On this page" outline show the same teal badge, the overview nesting each form beneath it; and theb2d.shapebody, shape_indexform documents both of its arguments. - Each version note in the API reference leads with the
N/C/Dchip its fact maps to instead of a grey bullet, such as the greenNbeforeSince Defold 1.13.0onb2d.body, and the chip stays when a narrower release range hides the heading's. In an overload block, a note every form shares sits once above the forms, and a note for one form sits right under that form's signature. - The Nakama server API spec (
heroiclabs/nakama) that nakama is checked against moves fromv3.40.0tov3.41.0. The client types you import still come fromheroiclabs/nakama-defoldv3.4.0and are unchanged.
Fixed
- An extension whose
.script_apiwrites a type as a list (type: [table, string]) is typed as that union by resolve instead ofunknown. - Symbol names mentioned in API reference prose link to their reference on the published site instead of opening a missing page.
- Math symbols and other special characters in the engine reference show as characters in editor hovers and on API reference pages, such as
P ⋅ Q = |P| |Q| cos θforvmath.dot, instead of entity source like⋅. - Declarations that the engine's own examples or descriptions contradict are corrected, so code written the way the reference shows it type-checks:
go.get/go.set— thekeyoption accepts a string as well as a hash,keystakes an array of hashes or strings, andgo.setaccepts an array ofvmath.vector4to set a material property array.go.delete(true)deletes the calling object and its children.- Component property keys —
go.get<model.properties>()reads"texture0"through"texture7"instead of thetextureNplaceholder from the model reference, sprite adds"texture0", and a newmesh.propertiescatalog declares"vertices", all typedHash. render.constant_buffer()— the buffer takes named constants, single or array, as inconstants.tint = vmath.vector4(1, 1, 1, 1).- Render targets and textures —
render.set_render_target,get_render_target_width/_height,set_render_target_sizeandenable_texturetake a render target resource by name, andset_render_targettakesrender.RENDER_TARGET_DEFAULTand a list ofgraphics.BUFFER_TYPE_*constants asoptions.transient.enable_texturebinds a render target or a numeric texture handle,disable_texturetakes a texture unit, andset_cameratakes a camera URL string. - String-keyed tables —
compute.set_textures,material.set_texturesand thehttp.requestheadersaccept an object literal as well as aLuaMap.collectionfactory.createpropertiesis keyed by instance id, as aLuaMap<Hash, …>or an object literal, so a table keyed by property names such as{ speed: 2 }reports an error. pprint— takes any number of values, as inpprint("MOUNTS", mounts).gui.set— takes avmath.matrix4material constant, a hash such as a runtime texture, and a stringoptions.keysuch as"my_font_name";gui.set_rotationtakes Euler angles as avmath.vector3.b2d.shape— every function that takes a shape handle also takesbody, shape_index, as inb2d.shape.get_shape(body, 1), andset_shapemay omitupdate_mass.- Atlas animations —
playbackinresource.set_atlas,create_atlasandget_atlasis ago.Playback, so it takesgo.PLAYBACK_LOOP_PINGPONGinstead of rejecting every constant. sys.save/sys.serialize— take a Lua sequence such as["my_value"].- Buffers —
buffer.createtakes its stream declarations as an array of{ name, type, count }records whosetypeis abuffer.ValueType.stream.length()returns the element count and compiles to Lua's#stream, andbuffer.get_bytestakes the stream name as a string. msg.post— a message id with no declared payload also accepts a Lua sequence, such as[t_volume].http.request,sprite.play_flipbookandcollectionproxy.loadcallbacks — receive the documentedresponsetable (status,response,headers, progress and range fields) and completionmessage(current_tile,id), withHashmessage ids andUrlsenders, instead ofunknown.socket.newtry/socket.protect—socket.newtry()may omit its finalizer, and a try function returns the value it unwraps, such as the client fromtry_(conn, err)afterconst [conn, err] = socket.connect(host, port), while rejecting an undestructured multi-return that Lua would receive as one always-truthy table. A protected function returnsnilplus the error message.render.CONTEXT_EVENT_CONTEXT_LOST/_RESTOREDandgraphics.SEMANTIC_TYPE_*— declared; the engine defines them, but the reference names them only in prose. TheSEMANTIC_TYPE_*constants follow each release's own list: none on 1.12.4, twelve on 1.13.0, andSEMANTIC_TYPE_MORPH_TARGET_WEIGHTSfrom 1.13.1.
- Every hover and API reference example type-checks at the strictness
defold-typescript initsets up. Examples return script state frominit(such asrender.drawandvmath.lerp), check a value that can be missing before using it (image.load,camera.screen_to_world), use the constants the declarations export (gui.EASING_LINEAR,sys.REQUEST_STATUS_FINISHED), give each of several examples on one page its own scope (sys.get_host_path), and destructure a multi-return before handing it to a try function, so thesocket.newtryandsocket.protectexamples catch errors.
v0.39.0 - 2026-09-23
Improved
- sprite_repeat and node_repeat (
Dragosha/defold-sprite-repeat, tagv0.3) now have types, soresolvegives a project that depends on the library typed imports for tiling a sprite or GUI box node texture, including theanimate,stopandupdatecalls on the handlecreatereturns. resource.create_textureacceptspage_count, the array-texture page count the engine reads and upstream's own example passes, so creating a texture array type-checks without a cast. The reference's own<dl>omits the field; every documented field it lists stays as the reference declares it.- Native extensions that ship no
.script_apican now be typed:resolvewrites a curated namespace into.defold-types/extensions/for DAABBCC (daabbcc), defold-sharing (share), defold-uuid4 (uuid4) and defold-tile-raycast (tile_raycast) once the archive'sext.manifestconfirms the match,resolve --jsonreports each astypeSurface: "vendored-native", and each/apipage defines the result and option shapes its signatures name. Where an extension's bundled annotations disagree with its C++ source, the types follow the C++, sodaabbcc.rebuild_all(undefined, full)passes the flag in the second position the runtime reads. - The API reference shows authored TypeScript examples. 329 functions carry a hand-authored body, and both the canonical
/api/<namespace>pages and the version-pinned ones such as/api/defold-1.13.1/resourcerender it wherever the example's source hash resolves; an example with no resolving authored body shows the reference's own Lua — see resource. - Every documented constant enum has a name you can write. A parameter that spelled out 41 branded
gui.EASING_*arms readsgui.Easing— exported from the namespace it belongs to (gui, go, graphics, render, window and the rest), with separate names where a getter and its setter accept different members, such as window'sDimModeStateandDimModeStateSettable— so signatures and hovers stay legible and your own wrapper can take one instead of falling back tonumber. Each alias has an API-reference entry listing its members, and every mention links to it from the signature and from the Parameters and Returns breakdown beneath it, landing on the entry for the version you are reading.
Fixed
- Four defect classes are cleared from the
@exampleshipped on each declaration, so many more of them compile — and build what they then use — when you copy one out of a hover or the API reference. Examples outside these classes still carry type errors, mostly wrong property and argument types.- Wrong script factory — 21 gui and render functions called
defineScript, which a gui script or render script cannot import. Each now calls the factory its own script kind exports,defineGuiScriptordefineRenderScript. - Undeclared names — 49 functions used names the example itself never introduced, leaving
srcbuffer,urlorselfundefined. Each body declares every ordinary local with the real API that produces it, getsselfthe way real code does — from the script factory its own kind exports, or as a parameter where the example is documented across several kinds — and what it declares is a resource the rest of the body validly uses: a render target is freed once from a teardown hook and declares every attachment it is queried for, and a resource array texture narrows the resource and image it loads before reading them, holds every page written to it, and is created at the dimensions of the image it decodes — on every pinneddefold-targetthat ships the example. - Untyped helper parameters — a helper in 16 examples left its parameters untyped, which the
strict: trueprojectinitscaffolds rejects withTS7006. Every parameter now carries the type the API it is passed to declares, or theselffields the body reads. - Several examples run together — 35 functions, across go, gui, render, resource and the script callbacks, document more than one example and shipped them concatenated into a single block; 15 of those blocks stacked two or more
export defaultand could never compile, and the other 20 compiled only as one welded program, with the sentences separating the examples folded into the fence as comments and colliding names renamed to keep it valid. Each example is now its own@exampleblock in the hover and on the API reference, led by the sentence the reference writes above it, and carrying everything that example needs on its own.
- Wrong script factory — 21 gui and render functions called
- Reference descriptions reach you whole, in an editor hover and on the API reference. Three ways the reference's own markup broke the render are repaired in the one converter both surfaces read.
- Unclosed code block — three resource parameter and return descriptions open a Lua block upstream and never close it, swallowing everything after it; the closing fence is supplied now, so a hover still shows the
@examplethat follows and/api/resourcerenders all 24 of its symbols outside the block. - Heading welded into the Lua — ten resource, go and gui examples pack several examples into one highlight block using the reference's own fence markers, which rendered as lines of code; each example is a code block of its own now, with the heading as prose between them.
- Bullet with no value — 41 resource bullets showed an empty
-with the value they described adrift below the list, on every pinneddefold-target; each marker now carries its value.
- Unclosed code block — three resource parameter and return descriptions open a Lua block upstream and never close it, swallowing everything after it; the closing fence is supplied now, so a hover still shows the
watchno longer repeats "attached to Defold editor" after the machine sleeps or the editor's console connection drops, and no longer repeats the editor version warning with it.
v0.38.0 - 2026-09-21
Improved
- Messages can be typed where they are sent and handled, with no program-wide declaration required — see Ways to type your messages. An undeclared string remains a valid
msg.postmessage id; the one build change is theonMessagefix below.msg.postcompletion lists every built-in id and every id declared in CustomMessages, and any other string still compiles.- Handler annotation — annotating a handler's
messageinonMessagedeclares that id for the script, a numeric key under its string form (1e3is"1000"), andScriptMessages<typeof script>reads the ids back offdefineScript,defineGuiScriptordefineRenderScript. - Typed receiver —
msg.url<M>(...)returns an address that makesmsg.postcomplete and check the receiver's own ids. - Scene address —
scene-typeslinks each script component's address to thedefineScriptsource that builds it, somsg.post("/logic#wave", ...)completes and checks that script's ids with no import.
Fixed
- An
onMessagehandler under a computed key such as[WAVE](withconst WAVE = "spawn_wave"), or written as shorthand{ onHit }, built without an error but never ran. A key like[WAVE]now handles"spawn_wave", and any handler the build cannot wire up fails the build at that line — see the examples.
v0.37.0 - 2026-09-20
Breaking
- A pure-Lua library that ships its own
.script_apinow gets this toolchain's curated types instead of an ambient namespace generated from that doc.resolvematches each dependency against the vendored corpus first, so a confirmed match such as boom or bridge is imported by itsrequirepath (import * as boom from 'boom.boom') and the staleextensions/namespace an earlier run wrote is pruned with its tsconfig entry. A match the archive does not confirm changes nothing: it is reported as an unverified library only when the dependency is asset-only, and otherwise keeps its own.script_apinamespace with no entry and no warning. initwrites no debug file;setup-debugwrites the whole debug path. Thelaunch.jsonconfiguration, thedefold-debug.tsBun launcher and the Local Lua Debugger recommendation arrive with thegame.projectdependency, the ambient declaration and the entry-script bootstrap, so a scaffolded project stops advertising a debugger nothing has wired; alaunch.jsonthe command cannot parse stops it by name with the project left untouched.upgradeandinit . --forcerefresh the two derived fields of a launch configuration already present and create none.- Five return types now carry what the engine actually returns, matching the reference and the
@exampleshipped beside them. Three of them gain values that can be absent, so the call sites below need a??default or a narrowing check.resource.get_render_target_info— the per-attachment fields (handle,width,height,depth,mipmaps,type,buffer_type,texture) sat beside the top-levelhandleinstead of inside the documentedattachmentsarray. Read them asinfo.attachments[0].handle;textureis optional, since the reference documents it only for a render target passed in as a resource.window.get_safe_area— the eight keys were wrapped in asafe_arealevel the engine never returns. Drop it:window.get_safe_area().inset_left.sys.get_sys_info—device_model,manufacturer,device_identanduser_agentare optional, since the reference gates each on iOS, Android or HTML5 and Lua leaves the key out elsewhere. The other fields are unchanged.sys.get_ifaddrs—addressandmacare optional, which the reference has always said: "might benilif not available".b2d.get_body— returnsundefinedwhen the url names no collision object, as the reference's "Otherwise nil" says.
Improved
- The scaffold now follows your
tsconfig.jsonincludeandoutDirinstead of assumingsrc/.initseeds the startermain.tsunder the firstincludepattern that admits its ownmain.ts— an exact-fileincludesuch as["src/main.ts"]among them — and points the generatedmain/main.collectionat the componentbuildemits for it, reporting the patterns it searched instead of scaffolding when none of them does. The managed.gitignore,biome.jsonandLua.workspace.ignoreDirrules read the sameinclude— a re-init (or anupgrade) retires the oldersrc-shaped rules, so a generated.luamodule shows up ingit statusunless you setoutDir, and abiome.jsonyou have hand-edited to hold comments is reported for you to edit rather than rewritten. resolve --jsonnow says which type surface each dependency contributed. Everyextensions[]entry carriestypeSurface—"extension","vendored-library"or"none"— so an emptynamespacesreads as the normal outcome it is rather than a failure, and summingextensions[].namespaceswithlibraries[].modulescounts each module exactly once. Every declared dependency keeps its entry, pin fields included.
Fixed
upgradeandinit . --forcenow leave a current.vscode/launch.jsonexactly as you wrote it. Both rewrote the file from its parse tree on every run, dropping your//comments and hand indentation even when neither derived field had changed.resolvenow clears the extension surface when nothing declares one. Removing the last.script_apidependency — or every[dependencies]entry — used to leave.defold-types/extensions/and its"extensions"tsconfig entry behind, so retired ambient declarations kept loading; all three surfaces now reconcile to exactly what is declared.- Debugging now follows your configured sources instead of assuming
src/, on both ends.setup-debugpicks the entry script, cleans up stale blocks and writes the ambientlldebugger.debug.d.tsnext to that script off yourinclude, refusing a target that is not a configured production source by name and cause — outside the patterns, a declaration file, or under a generated or dependency tree such asbuild/node_modules; and thelaunch.jsonit writes derives itsscriptFilesandscriptRootsfromincludeandoutDir, so a breakpoint binds in a gui script, a render script or a plain.luamodule wherever the build writes it.upgrade, andinit . --force, rewrite those two fields in place when your inputs move, leaving the rest of the configuration alone.
v0.36.0 - 2026-09-17
Breaking
render.clear's buffer table is now keyed by the threegraphics.BUFFER_TYPE_*constants its reference names, not by any number.LuaMap<number, number | Vector4>no longer compiles —LuaMap's key type is invariant — so declare itLuaMap<render.ClearBufferKey, number | Vector4>, an alias exported on the default surface and every pinneddefold-target(Lua table constructs).buildandwatchnow reject three output arrangements they used to emit silently, each naming the file and what to change.buildexits non-zero having written no Lua;watchreports the same diagnostics and keeps watching, rebuilding once you fix the file. Type-only imports, and arequirewith no TypeScript source behind it such as a library's Lua orlldebugger.debug, are still left alone.- Unreachable
require— every emittedrequireis checked against the outputs the build writes, naming the importing file, the path Defold looks for and the path written. A dot in a source name is rejected rather than repaired, so rename the source. - Unsplittable script — a script whose exported values cannot be told apart from its lifecycle hooks: a top-level binding reassigned in one and read in the other, whatever the rebinding's spelling, or effectful top-level work above an exported declaration. Both are fixed by the module singleton script state already teaches.
- Contested output path — a path claimed by two sources, or one already holding Lua the build did not generate, reported before anything is written so that file is left byte-for-byte alone. The generated
lualib_bundle.luaanddefold_typescript_timers.luaare inside the same contract, so a hand-authored file at either output-root path has to be renamed.
- Unreachable
Improved
- A script can now export runtime values other sources import. A source that calls a lifecycle factory and exports values builds into two files — the component, and a companion Lua module beside it (
src/door.ts->src/door.ts.scriptandsrc/door.lua) carrying exactly the exports and the declarations they reach, so a value only the script uses stays in the script alone. The component requires the companion rather than redeclaring it, so an exported object is one table for the script and every importer, under a configuredoutDiras much as alongside the sources (script state). - Lua table constructs is a new guide page on writing a table the engine reads by constant key, such as
render.clear's buffer table: why the object literal does not compile, the checkedLuaMaproute and the inline cast, and the mapped type that looks like the fix while silently accepting a key from another family. - Script lifecycle now lays out all three ways to type
selfand what inference costs. It coversinit(self): StateanddefineScript<Props, State>beside the inferred default, why one type argument cannot sit next toproperties, and that a type argument describes state without creating it — a field noinitwrites isnilon a fresh instance.
Fixed
- A project with a configured
outDirnow loads whatbuildwrites. Every emittedrequire— a cross-file import, and the generatedlualib_bundle.luaanddefold_typescript_timers.lua— used to keep its source-tree spelling while the file was written under theoutDir, so Defold found nothing at load time; each now names the path the build wrote. AnoutDirwhose own name contains a dot can be named by norequireat all and fails the build before anything is written. - A timers-only project now gets the
lualib_bundle.luaits runtime requires. The generated timer runtime has always required the bundle, but nothing asked for it to be written unless some source also used a helper likeObject.keys, so such a project loaded a file the build never wrote. - The
fontnamespace now exists on the default surface. It shipped in the per-kind subpaths and every pinneddefold-targetbut was missing from the package's own entrypoint, sofont.add_font(...)failed to compile for a project that imports@defold-typescript/typesdirectly. - Three API reference code examples now compile.
render.clearpassed an object literal where the signature takes aLuaMap,zlib.inflate's sample payload used string escapes TypeScript rejects outright, andfactory.createput twoexport defaults in one block; each is now copy-pasteable, and every hand-authored example is type-checked against the surfaces that ship it so a new one cannot regress. - API reference Parameters and Returns entries now show the same type as the signature above them, on each overload's own row. Slots whose real type the typings recovered —
render.clear's buffer table,render.enable_state's state constant,b2d.body.create_fixture's fixture-definition table, and every other curated mapping, documented constant or recovered options table — used to readRecord<string | number, unknown>orOpaque<"constant">in the breakdown while the signature showed the branded type you actually pass.
v0.35.0 - 2026-09-16
Breaking
- A constant-typed function argument whose reference documentation names constants the typings declare now accepts only those constants. Passing such an argument a generic
Opaque<"constant">, a constant from another family (gui.PLAYBACK_ONCE_FORWARDintomodel.play_anim), or the result ofwindow.get_dim_mode(), which can beDIMMING_UNKNOWN, intowindow.set_dim_modeno longer compiles; pass the documented constant instead (enum constants). @defold-typescript/typesno longer declaresiac,iap,pushorwebview, on the default surface or any pinneddefold-target. A project that calls them must add the extension as adependencies#Nentry ingame.projectand runresolve, which types them like every other extension (native extensions).
Improved
- Documented constants now compile where the reference says to pass them, and getter results compare against their constants.
gui.animate(node, gui.PROP_COLOR, to, gui.EASING_INOUTQUAD, 0.5)and the otherguisetters,render.enable_state(graphics.STATE_DEPTH_TEST)inrender, and theprofiler,model,windowandbuffermetadata calls type-check, andsys.get_connectivity() === sys.NETWORK_CONNECTEDis no longer rejected as a comparison that can never be true. - CLI failure lines now read
defold-typescript <command>: error: <message>and non-fatal problems… warning: <message>, with the word bold red or yellow on a terminal, and theERROR:/WARNING:tag of Defold console lines forwarded bywatchandreloadis colored the same way.resolve's scene-source warnings now carry the command prefix,--no-color,NO_COLOR,TERM=dumband--jsonturn color off, and--jsonpayloads are unchanged (terminal output). watchkeeps itself attached to whichever Defold editor is running, and checks that editor's version.- Attaching — it looks for an editor about once a second while none is attached, so an editor opened at any time is attached and one that quits is reported, without waiting for a file save. Runtime errors from a game launched before your first edit reach the terminal straight away, and an editor whose console fails to open is retried at growing intervals until it opens or the editor quits.
- Version check — an editor attaching after startup is version-checked: a mismatch with a concrete
defold-targetpin prints theset-target --detectednotice, an unpinned watch names both versions and asks for a restart, and--jsonreports it as aneditorVersionevent. A version matching the target, the one startup compared, or the last one reported is not repeated, a check whose own editor quit or was replaced before it finished reports nothing, and the exit status is never affected.
Fixed
render.render_target({...})andvmath.euler_to_quat(v)now compile. The engine accepts a lone parameter table and a lone vector3 — the calls the reference's own examples make — but the typings required the two- and three-argument forms; both spellings of each call now type-check on the default surface and on every pinneddefold-target.- Hand-authored engine overloads now show every overload form on the canonical API reference pages.
go.get,go.set,go.property,msg.post,msg.url,render.render_targetand thevmathgenerics list each arm on their unversioned/api/<namespace>page, which previously showed a single stale generated signature; the same arms are one entry each inllms-full.txt. reloadexits 1 when the editor console closes or fails before its--waitwindow ends. Such a reload used to exit 0 with "no error observed" even though the rest of the window went unread;--jsonnow reportsconsoleWindowCompleteso an emptyconsoleErrorscan be trusted only when it istrue.watchkeeps an editor that replaced another one attached when the old editor's console closes. The replacement is no longer detached and announced a second time, and its runtime errors keep reaching the terminal.
v0.34.0 - 2026-09-13
Improved
- Every Defold library is now listed under Libraries › defold, which leads the sidebar and the Libraries page marked
(official). Each.script_apiadefoldGitHub org repo ships gets a page at its pin, with setup steps matching that release, tag or commit, and each repo with no typed API gets its own icon-marked page and sidebar entry, such as extension-qrcode, describing what it ships with the same GitHub pin and setup steps as a typed library page — except that placeholder repos show no install step and fork-only repos start with forking;iac,iap,pushandwebviewmoved there from the engine reference, and their/api/links still work. - Defold library pages show each extension's constants, code examples, callback arguments and optional parameters. Pages such as
admobandiapcarry a Constants section and the upstream usage examples, list a callback's arguments and a table's fields nested under their parameter, and mark optional parameters with?. - Lua and TypeScript code samples in the guide and API reference are labelled with their language. A small badge shows the language's logo and name beside a sample's file name, or on the block's top edge when it has none, and copying a sample never includes it.
- Platform and caution markers in the API reference now show as platform logos and icons whose label appears on hover or keyboard focus, with caution icons tinted like a warning callout. Notes such as "iOS only" or "attention" on pages like
sysandiapused to vanish or read as[icon:ios]bracket text; library cards and symbol tooltips now drop the brackets.
Fixed
- A native extension's branded engine types now type as brands instead of silently becoming
any. The materialized extension surface named a brand import that resolved nowhere from where it was written, so under the scaffold'sskipLibCheckeveryHash,Url,Vector3and node handle in an extension's signatures widened toanyand stopped catching wrong arguments — worst on extensions like Spine, whose signatures are branded almost throughout. Extensions also gains a section on extensions that add members to an engine-owned namespace. webview.create,webview.evalandwebview.is_visiblenow returnnumberinstead ofvoid. The webview id, request id and visibility flag they hand back can be stored and passed on without a cast.
v0.33.1 - 2026-09-10
Improved
- The gotchas page now says which absence spelling an engine slot accepts. typescript-gotchas gains a worked passage on passing
undefined— nevernull— to an optional argument, and the Lua-comparison and lifecycle pages point at it rather than leaving thenilcollapse to read as permission to passnull.
Fixed
- 21 engine parameters the reference itself shows being omitted are now optional. The
resourcetexture-creation buffers and the async callback, theguitextureflip,sys.set_engine_throttle's cooldown, theb2dshape/fixture/joint slots andiap.buy's options all rejected the calls their own docs teach, sosys.set_engine_throttle(false)andiap.buy("sword")now compile. msg.urlnow acceptsundefinedwherever the engine acceptsnil— as the socket of the three-argument form, addressing the current game world, and as the single argument, addressing the current script. The two-argument call stays rejected.
v0.33.0 - 2026-09-08
Breaking
- Refreshing the bundled library pins changes declarations a project may already be calling.
- druid breaks two call sites at
1.3.1: textset_textnow requires the new text as an argument and returns the component, so a baretext:set_text()no longer compiles, and a button'sstyleis now the typeddruid_button_stylerather than a plainLuaTable, so a value declaredLuaTableno longer assigns to it. - decore changes six declarations across
4->6, two of them without a compiler error.event_bus.process_alland the tiny-ecssystem.nocacheopt-out are gone.process_allfolded intoprocess, andnocachewent with the shape cache that replaced it; both were call-site-visible, so a project using either must move before taking this release.event_bus.triggernow takes the entity second. A writtentrigger(name, payload)binds the payload to the entity slot — move it to the third argument. The compiler often will not catch this, because every field ofentityis optional.event_bus.processcalls back once per entity. The callback takes(entity, data)rather than the event list, and the call returns both the events and their entities.event_bus.set_merge_policyandmerge_callbacksre-shaped the merge callback to(entity, data, datas, entity_map). An existing inline callback keeps compiling with every parameter silently re-bound, so read each body rather than trusting a green build.event_bus.get_eventsandget_stashchanged shape.get_eventsnow requires the event name its old declaration wrongly omitted, andget_stashyieldsunknownelements rather thanLuaTable, so using one as a table needs a cast.world.findEntitiesrequires theoutbuffer. A three-argument call through theworldfield needs an explicitundefinedfourth argument; the module-levelfind_entitiestakes the same buffer optionally.
- event no longer declares
promise.cancellation. Upstream marked the field private at21, so it is hidden from the generated declarations and the/apidocs like every other non-public member. Readpromise.on_cancelinstead: it is the same event object the old field reached throughcancellation.on_cancel, now published on the promise itself. - log no longer declares
get_default_logger_name. Upstream moved it out of the public module at7, and there is no replacement — the default logger name is now derived internally — so a project calling it must supply its own name toget_logger.
- druid breaks two call sites at
Improved
- The bundled library pins are being refreshed against their current upstream releases.
- druid moves from
1.2.5to1.3.1, addingget_value/set_valueon progress,is_enabled/set_enabledon swipe,set_valueon timer,set_justify/is_justifyon rich text,add_drag_action/remove_drag_actionon drag,refreshon data list andget_text_visualon input. Several existing declarations widened without breaking a call site —get_widgettakes an optionaltemplate, the druid instance'sset_whitelist/set_blacklistmade their argument optional, and a buttoncallbacknow receives the caller, the custom args and the button — while the internal_on_mouse_hoveron scroll is gone. - decore moves from
4to6, adding aremove_componentmodule function, an optionaloutbuffer onfind_entities, entity-parallel event-bus storage (event_entities,stash_entitiesand their getters) and per-phase system lists onworld. Event ids now accept aHashas well as astring, andget_eventstakes the event name its old declaration wrongly omitted. - event moves from
19to21, publishingon_canceldirectly on a promise so cancellation cleanup no longer reaches through an internal context field.cancelis narrowed to in-progress work — a promise that already settled is left alone, while pending descendants are still rejected and still trigger the sharedon_cancel. - log moves from
6to7, adding a file-output API (set_file,get_file,clear_log_files,finaland the per-loggerset_file_nearby) and custom log handlers (add_callback,remove_callback,clear_callbacks). The level methods now accept a nil message, andget_default_logger_nameis gone. - panthera moves from
runtime.8toruntime.10, a purely additive release: the animation state gains the fields the new clip playback path exposes (clips,template_states,play_animation,play_options,play_sample_depthand a reusablecollect_buffer), and three supporting types are now declared. Nothing was removed and no existing declaration changed, so no call site moves. - bridge moves from
v2.0.0tov2.1.0, adding anotificationsAPI:schedulea notification the platform shows after the player leaves the game,cancelone by id orcancel_all, andis_supportedto check the platform first. Nothing was removed and no existing declaration changed.
- druid moves from
- Refreshing library pins is a new guide page for moving a bundled library to a newer upstream release. It gives the regeneration commands per lane — including why the hand-vendored authored lane has no fetch step — and names both what a bump moves with it (the committed fidelity floor, the snapshot digest, the docs-site provenance assertions, the generated docs artifacts) and what it must leave alone, including the consumer test fixtures that pin the very same version string, which is why a repo-wide find-and-replace is unsafe and a green suite is no proof it was done right.
v0.32.1 - 2026-09-06
Fixed
- The
go.propertyreference no longer teaches the call this toolchain deprecates. Its entry now leads with a warning naming thedefineScript({ properties })field, and its TypeScript example declares the property there. Script properties onselfexplains what a direct call costs — the property registers at runtime but never reachesself's type, so reading it is a compile error — and shows the before/after migration.
v0.32.0 - 2026-09-05
Breaking
- The toolchain is now supported on Bun
>= 1.4. Every CI and release leg runs that minor and the getting-started floor names it; Bun 1.3 is no longer tested, so upgrade Bun before taking this release. go.get,go.setandgo.propertyno longer name a resource handle nothing hands out. TheOpaque<"resource">member is gone fromgo.get's andgo.set's fallback value union, andgo.property's deprecated resource overload with it; since the shipped API never produced that handle, no value you can get out of these declarations loses a call site. A resource brand you declared or asserted by hand no longer satisfiesgo.setorgo.property— pass theHashtheresource.*functions actually return.
Improved
- Your project's own message ids can now carry a typed payload. Declare them as string keys of the ambient
CustomMessagesinterface andmsg.post,isMessageandonMessagecheck and narrow them exactly like a built-in message, while the emitted Lua stays byte-for-byte what it was. messages carries the recipe, a worked cross-object example, and where a declaration may live — beside the payload type it names, or in a mapping-table.d.ts— along with the two shapes that quietly do not register.
Fixed
- The
cameraandspriteproperty catalogs now report the types the engine really uses. All eightcamera.propertiesmembers read asunknown, so everygo.get<camera.properties>()needed a cast; they are nownumber, withcamera.projectionandcamera.viewtypedMatrix4andsprite.frame_counttypednumberwhere the reference data says otherwise.
v0.31.0 - 2026-09-03
Improved
build,watch,run,upgradeandbobname a newer Defold release when one exists upstream of your pin. Checked at most once a day against a per-user cache, advisory only, and silent when you are offline;--jsoncarries it asupstreamRelease: { current, latest }, and--no-update-checkorDEFOLD_TYPESCRIPT_NO_UPDATE_CHECKturns it off.scene-typesaddresses now name the object and world they resolve in, cover your libraries, and stay current by themselves.- Worlds. A collection opened through a collection proxy is offered as
mylevel:/enemyrather than a bare path, and a collection factory's prototype is offered no static address, so the editor stops suggesting paths that resolve in the wrong world. - Objects. Component ids are offered object-qualified —
/player/player#spritebeside the bare#sprite— so an id is never suggested on an object that does not own it. - Libraries.
resolveunpacks each dependency's scenes and merges their component ids, object paths and animation ids into your own under the address Defold uses, your file winning a collision. A dependency you declared but have not resolved is now named on the warning channel rather than silently skipped. - Freshness. Saving a
.collectionproxy,.collectionfactoryorgame.projectregenerates the declaration too, sowatchno longer serves the wrong world's addresses until you restart it.
- Worlds. A collection opened through a collection proxy is offered as
- The editor completes more of what you type inside a quoted name, and its panel says where each suggestion is valid.
- Relative addresses. An address slot also offers the forms valid from the file you are editing — sibling ids, deeper
sub/idpaths and their#fragmentjoins — while a bare/pathis offered only where your own script's world can reach it. model.play_anim. Itsanim_idcompletes from the.animationsetthe model your siblingurladdresses reads from, credited to the set that really lists each entry.gui.play_flipbook. Itsanimationcompletes from the textures of the one.guiscene owning your gui script, never a project-wide union.
- Relative addresses. An address slot also offers the forms valid from the file you are editing — sibling ids, deeper
build,watchand your editor flag address literals that cannot resolve, naming the file without failing the build. A#fragmentis checked against the components the addressed object really declares (unreachableAddresses), and a socket-qualified address such asmylevel:/enemywritten at a slot that resolves in the caller's own world is reported with the world your script actually runs in (crossWorldAddresses).--jsonrepeats both as structured entries, and the editor plugin shows them as suggestions so a broken address squiggles as you type whiletsc --noEmitstays clean.
Fixed
resolvecan no longer be made to write outside.defold-types/dependencies/. A dependency archive entry that traverses out with a..segment is refused and named onstderr, and the rest of that archive still unpacks; a directory merely starting with dots is an ordinary path.runno longer launches a cached stock engine and a build that record different Defold versions — the pairing that made Defold reportFORMAT_ERRORafter a pin bump. It now reports the two versions instead of launching; an engine cached before this release keeps launching until onebob runreplaces it.
v0.30.0 - 2026-08-30
Improved
scene-typesturns your project's scenes into completions, and keeps them current on its own. The game-object paths and component ids in every.collectionand.goland in.defold-types/scene-addresses.d.ts, whichinitandupgradename in yourtsconfig.json,buildrefreshes before it transpiles, andwatchrefreshes on every scene save — so address slots likemsg.post's receiver suggest real addresses while still accepting one composed at runtime, and you run the verb yourself only for a one-off or a CI step that runs neither.
Fixed
- A pinned Defold target can call the Lua standard library again. The surface written for a pin omitted the
lua-typesreferences the package entrypoint carries, somath,string,table,osandbitstopped resolving in your own sources the moment you pinned; both writers now lead the surface'sindex.d.tswith them. - The editor plugin now loads in a real editor.
@defold-typescript/tstl-pluginexposed only an ESM entry, which the TypeScript language server loads and then skips for not being a plugin factory — so scene completions, the provenance panel, and the unreachable-#fragmentsuggestion never appeared outside the test suite; the package now ships arequire-shaped entry the plugin loader accepts. watchkeeps the scene-address declaration current on a pinned Defold target too. A pinned project wired neither the scene watcher nor the generator, so the declaration was never written at startup and never refreshed when you saved a.goor.collection— an unpinned project already did both.
v0.29.0 - 2026-08-29
Breaking
physics.get_shapenow types its result as the variant record it is. The declaration listeddiametertwice — invalid TypeScript thatskipLibCheckhid — and marked every shape-kind field required;diameter,dimensionsandheightare now optional, so reading one takes a narrow (if (shape.diameter !== undefined)).physics.set_shapetakes the same field set and loses its duplicate too.
Improved
- Converting a project no longer tells you to run
init-agentsfirst.initalready writes theAGENTS.md/CLAUDE.mdagent contract, so Getting started now namesinit-agentsonly as the repair for a contract that is missing or has lost its managed block. - The guide now says
src/is a default, not a fixed location. Every page that namessrc/as where your TypeScript lives carries a footnote pointing at theincludeglobs intsconfig.json— the scopebuildandwatchactually compile. - A typedef in the API reference now has its own heading, and signatures link to it. Each shape a page documents gets a heading of its own in the "On this page" list instead of sharing one
Typessection, and a parameter or return type naming one of that page's shapes links straight to that shape's heading — including when the shape's name matches an earlier heading on the same page. - The API reference version range selector reads at a glance. The closed
From/Tochrome now shows the bare version behind a direction arrow instead of the word label plusDefold 1.13.0, and the fullDefold <semver>label still names every option once the dropdown is open.
Fixed
- A pinned Defold target now gets the same typed surface as an unpinned project. Every surface the toolchain writes for a pin was missing the hand-authored augmentations — the
vmath,goandmsgoverloads, the message and window-event guards, and the globalhash/pprintdeclarations — along with the built-in message table those guards and overloads are written against, so code that compiled unpinned stopped compiling once you pinned andmsg.postpayload checking quietly fell back toany.
v0.28.3 - 2026-08-27
Fixed
init-agentshas its own CLI page, listed with the other verbs: what the managedAGENTS.mdblock carries, why re-runs never touch your own notes, how it differs from the contractinitandupgradealready write, and its--jsonenvelope.- A re-run that changes nothing now leaves
AGENTS.mdalone.init-agents(andinit --force) used to rewrite an already-current contract and report it as written; the file keeps its timestamp and the--jsonwrittenlist stays empty. - The usage line names every command. Running the CLI with no verb, or an unrecognized one, printed a list that omitted
set-target,upgrade, andreload; it now lists them all and points at--helpfor each command's flags.
v0.28.2 - 2026-08-27
Improved
- The Defold version can come from the editor you already have open. With this project open in the editor, version resolution asks that editor directly instead of guessing at an install path.
set-target --detected— pins the version you are actually running, not whatever a conventional install path happens to hold.- Pin-drift notice — compares your pin against that same live version, so
buildandwatchstop reporting drift against an editor you are not using. - Nothing open, or an editor gone quiet — unchanged behaviour: detection falls back to reading the editor's
configon disk, and an editor that stops answering is abandoned rather than left holding the command.
Fixed
set-target --detectedfinds editors the toolchain would not have guessed, and says where it looked when it still cannot.DEFOLD_TYPESCRIPT_EDITOR— point it at the folder holding the editor'sconfigand it is read ahead of the conventional per-OS locations. This is the answer for a Windows install, which is a portable archive you extract wherever you like.- Failure message — a miss now lists every path it read and why, instead of telling you to install the Defold you already have.
v0.28.1 - 2026-08-26
Fixed
set-targethas its own CLI page — its version and channel tokens,--detected, the rejected-version error, and its--jsonenvelope. The verb that changes thedefold-targetpin was documented only inside Pinning the Defold target, which now opens by saying what a target selects and the two places you express it: that pin, and the per-run--defold-targetflag.
v0.28.0 - 2026-08-25
Improved
- The API reference can be read over a range of Defold releases, not just one. Paired
From/Todropdowns pick the range: every page and index then covers it whole, narrowingFromdrops the symbols that had already gone by then, and moving either bound keeps you on the page you were reading whenever the new range still covers it. See Reading the API reference over a range.- Symbols — a page covers every symbol that existed anywhere in the range, with an availability note naming the release that actually added or removed it.
- Signatures — a symbol shows the newest declaration made inside the range, or the one it was built with when the range declares none, so a deprecated symbol keeps its full declaration rather than a weaker one.
- Indexes — a version index now lists everything that version's pages cover, including namespaces removed in an earlier release and the Lua standard library, so it matches
/api; both state which releases are tracked and that an unmarked symbol is older than all of them. - Badges — the
New/Changed/Deprecatedmarkers and every count beside them, sidebar included, now describe movement inside the range you picked rather than across all tracked releases, so a same-release range marks nothingNeworChangedwhileDeprecatedstill follows theTobound and can mark it. Availability notes stay absolute, and the sidebar counts carry every category the range can reveal and announce the tally they are currently showing.
v0.27.0 - 2026-08-23
Improved
- Nothing you were already using disappears when something upgrades. A Defold patch release and a toolchain upgrade both used to overwrite the surface they replaced; each now lands beside it. See Pinning the Defold target.
- Defold targets — the target a patch replaces is demoted to a committed historical surface rather than overwritten, so it keeps resolving through
set-target. The toolchain ships the current release plus the previous minor pre-baked, and a bump reports every version that leaves that set. - Defold 1.13.0 — a shipped API target again:
set-target 1.13.0resolves, andbuildmaterializes its complete pre-baked surface, including its own editor-script API and the/api/defold-1.13.0/…reference pages. - Materialized directories —
.defold-types/defold-1.13.1@0.27.0/and.defold-types/libraries@0.27.0/now name the toolchain that wrote them, and are stamped only once every file has landed. Your tsconfig moves to the new names, and a run cut short reads as incomplete instead of vouching for contents it does not have.
- Defold targets — the target a patch replaces is demoted to a committed historical surface rather than overwritten, so it keeps resolving through
- Version notes name the release that actually changed a symbol. Across the API reference and its search,
computereadsSince Defold 1.13.0rather thanSince Defold 1.13.1. - A repeat
resolvereuses the library surface when your dependency set and the toolchain are both unchanged, instead of rewriting it.
Fixed
- A Defold pin now holds, and says so when it cannot. Five ways it used to fail quietly:
set-target— a version that never existed, such as1.42.99, printed a confident transition line and exited 0. The pin is now written only when the API registry can provide the version, and otherwise rejected with the resolvable targets listed, writing nothing either way;--detectedis checked identically, and channels still pass through.build,run,watch,upgrade,bob— a pin with no shipped API surface materialized nothing and exited 0 while your code kept compiling against the newer default. They now name the pin and the resolvable targets on stderr and in the--jsonwarnings, and--fail-on-driftturns it into a non-zero exit.- Package imports — one idiomatic
import { defineScript } from "@defold-typescript/types"merged the current API surface back over the pinned one for every file, so a project pinned to 1.12.4 still compiledcollectionproxy.load. A pin now binds the package specifier itself, and still serves the package's complete export set. - On-demand generation — the generator's own inputs were left out of the published package, so every target that is generated rather than pre-baked made
build --defold-target <version>reportcould not materializeand quietly keep the default surface. A checkout never saw it. - Code examples — a project pinned to 1.13.0 or 1.12.4 saw raw Lua in the
@exampleblock ofgui.setand six other calls. Every committed surface is now checked, so a Defold bump cannot silently regress one.
- A matched vendored library's types survive the next build. Once the library surface started naming its toolchain version, the
buildfollowing aresolvedropped thelibraries@<version>entry from yourtsconfig.json, so every library symbol stopped resolving until you re-ranresolve. - The prefixless globals are on the current Defold surface again.
hash,hash_to_hexandpprintreadRemoved in Defold 1.13.1across the API reference and its search, and the 1.13.1 version index rendered no Globals section.
v0.26.0 - 2026-08-20
Breaking
- The pinned Defold target is now 1.13.1, and 1.13.0 is gone. A patch release replaces its predecessor rather than sitting beside it, so
defold-1.13.0is no longer a shipped API surface:--defold-target 1.13.0stops resolving and the/api/defold-1.13.0/…reference pages are retired. Move the pin to1.13.1— a project already on 1.13.0 needs no source migration, and a project on 1.12.4 still migrates through the 1.13.0 notes, which stay under their own heading. See Pinning the Defold target. - The per-version upgrade page is now one evergreen guide. Upgrading Defold versions replaces
upgrading-to-defold-1-13-0.mdwith a version-agnostic runbook plus one## Defold <version>section per release, each keeping that release's own "what changed" notes, so the old page's URL no longer resolves. Each release's per-symbol notes are individually linkable headings and appear in the page's table of contents.
Improved
- Defold 1.13.1 brings two Lua API changes, both additive — nothing was removed or deprecated:
collectionproxy.load— loads and initializes a proxied collection, with the callback receivingproxy_loading,proxy_readyandproxy_error.gui.set— itsvalueparameter now acceptsnil, so a property can be cleared rather than only reassigned; existing calls are unaffected.
- A version note on an API reference page now names the version that changed the symbol, and reads before the description instead of after it. A symbol absent from the newest surface says
Removed in Defold 1.13.1rather thanAvailable through Defold 1.12.4, and one whose name survives under a new signature —gui.set, whosevaluenow acceptsnil— saysSignature changed in Defold 1.13.1instead of claiming it is gone. - Editor scripts gain the editor VM's
imagelibrary —image.load_file, thenimage.size,image.pixeland theimage.pixelsiterator over the loaded image.
v0.25.0 - 2026-08-18
Breaking
- starly is no longer part of the library corpus: its types, its reference page and its entry in the resolvable set are gone. The library was withdrawn upstream — its repository and its author's account were both deleted, it never published a release, and the only surviving copy is an unaffiliated third-party mirror — so no one can obtain a runtime for the declarations. For a 2D camera, use shutter, added this release as the closest replacement, or the longer-standing orthographic and rendy.
Improved
- The CLI now works with the running editor. A reload does not re-run
init, so whatever it set up belongs inon_reload, and Defold's own build errors still reach only the editor's Build Errors tab.watch --hot-reload— scaffolded as thedefold-typescript:watch-hrmise task, it pushes every successful rebuild into the running game, reloading nothing when a build fails, reloading the editor's extensions instead when the emit was an editor script, and naming the editor in your terminal when a reload is refused, after which it stops reporting that editor as attached until a reload actually lands; with or without that flag,watchprints the running game's runtime errors and warnings with their tracebacks into your terminal, and stopping it goes quiet at once — the console stream closes, a reload already on the wire is cancelled rather than left outstanding, and nothing further is reported: not a reload still waiting to attach, not the later commands of a reload that pushes more than one, and not agame.projectre-resolve that finishes after the stop.buildnames the editor it found under a timeout, so a stale port file pointing at a process that never answers is treated as no editor at all instead of holding the build.reload— a one-shot counterpart for scripts and agents: it pushes a single reload into the running game — or the editor's own extensions with--extensions— then reads the editor console for a bounded window (--wait, default 2s), exiting non-zero when the reloaded code throws, when the editor refuses, and when a requested window could not be opened at all; a stale editor port ends the command on a deadline instead of parking it. Exit 0 claims only that the post was accepted — plus a quiet console when a window was read, and nothing more under--wait 0, which opts out of the read entirely — and--jsonreports which of the two happened asconsoleObserved.- Console errors name your TypeScript — on both surfaces a reported location now carries the authored
.tsline and column in front of the generated chunk one (src/main.ts:5:11 (/src/main.ts.script:4)), read from the source map the build writes beside every output and naming the file you edit under any layout, including a project that builds into anoutDir, on the first build and on every rebuild alike. It is best-effort and never invents a location: a chunk with no usable map, a generated line the map does not cover, and a map resolving to anything that is not a file in your project are all left exactly as the console sent them, while underreload --jsonthe rawconsoleErrorsstay unchanged and the translations arrive beside them asconsoleErrorLocations.
- Editor scripts get a typed editor API. The new
@defold-typescript/types/editor-scriptentrypoint exports thedefineEditorScriptanddefineEditorCommandfactories — both erasing to plain tables the editor can load — and carries the editor VM without the game runtime:editor.get/bob/execute/transact/tx.*, theeditor.ui.*dialog toolkit andeditor.prefs.*(itsschemagroup and theCOLOR/SCOPE-style constant tables included, with every builder returning one nominal component handleeditor.ui.show_dialogaccepts), the VM's ownhttp,json,zip,zlib,pprint,localizationandtilemap.tileslibraries with every call shape Defold documents accepted as written (zip.pack(archive, ["build"]), a two-argumenthttp.server.route) andjson.decode/json.encodereturning real values rather than nothing, and a command'sactive/runopts bag typed from its ownquery, so a"one"selection reads as a single node, a"many"one as a list, and a member the query never declared is a compile error.wallnow offers a directory holding only editor scripts as a target like any other kind, so you no longer settypesby hand. - Walled directories follow your pinned Defold target. A pinned surface now carries the editor-scripting API of the target that declares one, and a wall narrowed to a pinned kind resolves both its ambient namespaces and its
@defold-typescript/types/<kind>factory import from that one surface — a target declaring no editor-script document of its own keeps the installed entrypoint, and a wall never narrows to a kind its surface did not write. That redirect is the only module mapping a wall manages and resolves against whateverbaseUrlyour roottsconfig.jsondeclares — absolute ones included — so the aliases your root and the wall's own config declare keep resolving inside a walled directory, and dropping the pin leaves them untouched. - New libraries in the corpus, each maintained here against its pinned upstream and materialized by
resolveonce you declare the dependency:- shutter (
Klaleus/defold-shutter) — a 2D camera covering the ground starly's withdrawal left open: the camera table, the three viewport behaviors, the screen/world conversions and the shake helpers. - nakama.socket and nakama.session (
heroiclabs/nakama-defold, pinv3.4.0) — the realtime socket's chat, match, matchmaking, party and status calls, each also bound onto the socket instancecreatereturns, plus the helpers that build, check, store and restore a session.match_createtakes a nil name to let the server generate one andmatch_jointakes either a match id or a matchmaker token, so unnamed creation and token-only joins type-check; the v0.24.0 note that a socket binding needed vendoring of your own no longer applies. - checkpoint (
Klaleus/defold-checkpoint) — the successor to the abandoned persist, typed for reading and writing save files as JSON or binary. It needsbritzl/defold-lfsat runtime, which this corpus does not type.
- shutter (
- The editor completes what your project declares. In an editor running the transpile-diagnostics plugin, the suggestions are listed after everything the editor already offers, nothing it offers is removed, and a caret inside a
hash("…")completes the slot the call around it occupies one level out, so the hashed form offers what the bare literal does while a doubledhash(hash("…"))offers nothing. They are read from an index the plugin holds across requests and refreshes whenever a file it reads changes, so completing repeatedly in one slot no longer re-walks your project and a newly authored id is offered without restarting the editor.- Game-object paths and component ids — inside an address argument the caret picks the half: from the
#onward you get the component ids your project's.goand.collectionfiles declare, replacing the#fragmentonly, and anywhere before it — including a literal carrying no#yet — you get the game-object paths those files compose, replacing the path half alone. A collection instanced inside another prefixes every path it holds (/player/player, never a bare/player), while achildren:edge is a transform relation and adds no segment. - Node ids — a caret inside
gui.get_node's argument offers the node ids of the one.guiscene that owns the script you are editing, replacing the whole quoted name; ownership is resolved through the sameoutDirandincluderules the build uses, so a project with a separate output tree completes too. A script no scene owns, or one that two scenes both claim, offers nothing. - Animation ids — a caret inside
sprite.play_flipbook'sidargument offers the animations declared by the atlas of the sprite the sibling argument addresses, again replacing the whole quoted name. The address must be the same-object"#id"literal: a path form, a variable or amsg.url(…)call names a component this file cannot decide, so nothing is offered. - Resource paths — a caret inside one of the six
resourceproperty constructors (atlas,buffer,font,material,texture,tile_source) offers the project's own files of the one kind that constructor accepts, as the/-prefixed paths Defold resolves.build/output and the directoriesinit's.defignorenames (node_modules,.defold-types,.vscode) are left out, as are the built-path slots and the extension-less loaders. - Config keys — a caret inside the
keyargument ofsys.get_config_string,sys.get_config_int,sys.get_config_numberorsys.get_config_booleanoffers theSECTION.KEYids your project's owngame.projectdeclares, replacing the whole quoted text. Only what that file writes is offered — a key it omits answers the reader's default at runtime — and a project without one offers nothing. - Action ids — a caret inside a
hash("…")compared against your handler'saction_id(action_id === hash(""), either operand order,defineScript'son_inputmethod included) offers the actions every.input_bindingin your project declares, replacing the whole quoted text. The comparison is what scopes it — ahash("…")carrying none, the hoistedconst JUMP = hash("jump")form included, offers nothing — and the slot is Defold's own ambienthash, so ahashyour project declares or imports itself is never offered ids. - Where a suggestion came from — highlighting one of these suggestions names the project files that declare it, every kind covered: the
.gofor a component id, the collection declaring a game-object path's leaf segment, the.atlasor.tilesourcean animation id was read from, the owning.guifor a node id,game.projectfor a config key, every.input_bindingthat declares an action. Inside an address the panel follows the caret's half exactly as the suggestions do, and anything the project cannot attribute exactly — a scene that failed to parse, a script two game objects both claim — keeps your editor's own panel rather than a guessed one.
- Game-object paths and component ids — inside an address argument the caret picks the half: from the
- Address slots say what they address. The 27 URL parameters that name a scene object — go's
id/urlslots, msg'sreceiverandurlstring— readSceneGameObjectAddress,SceneComponentAddressorSceneAddressinstead ofstring, so the reference distinguishes a game-object path from a component one. The aliases accept every string, so nothing that compiles today stops compiling. - A hashed name remembers the string it came from.
hash("#sprite")now reads asHash<"#sprite">rather than a bareHash, so the idiomaticconst SPRITE = hash("#sprite")still says which component it addresses. The parameter defaults tostringand constrains nothing, so every existingHashannotation and every call —hash("jump"),go.set("#sprite", hash("tint"), v)— compiles unchanged.
Fixed
runhands the engine every argument after--, including ones sharing a name with a CLI flag.run . -- --jsonnow launches the engine with--jsoninstead of consuming it and switching the CLI's own output into JSON mode.- Keys you add to a managed
mise.tomltask now surviveinitandupgrade, wherever in the task you wrote them and however TOML lets you spell the key — after a blank line, below a hand-edited multi-linerun, or written asenv . CONFIG,env."MY VAR"or an escaped"run"— and tables of your own, with whatever their values happen to contain, stay tables of your own. A refresh used to replace eachdefold-typescript:*block wholesale, end it at the first blank line, and judge a key by its raw spelling, so analias, adependsor a comment was dropped or hoisted into the root table and an escaped key was duplicated or quietly deleted, in the worst case leaving amise.tomlthatmiserefused to parse at all; a block now ends where its TOML table does, and only the keys that really meandescriptionandrunare rewritten. - A walled directory under a pinned surface no longer type-checks against the installed release's API alongside the pinned one. The
@defold-typescript/types/<kind>factory import used to resolve throughnode_modulesto the installed package, so the program saw the union of both surfaces and a call the pinned release does not declare compiled anyway; it is now the compile error it should always have been. - Reference-site corrections, each on what a page displayed rather than on what it documents:
- Libraries index — no longer credits the
ts-defold/libraryproject for its type definitions. Every library has been maintained in this repo since v0.24.0, generated from upstream sources that ship machine-readable types or hand-forked where upstream ships none. - persist and rendy — credited to their author's current GitHub account, so the attribution links no longer depend on a rename redirect.
- boom and deftest — the reference pages now show the type parameter their generic helpers take, instead of a signature naming a
Tit never declares. - Migrating from
ts-defold— the command surface it lists names every verb again, includingupgrade,set-target,reloadandrun, along withbob's full subcommand set.
- Libraries index — no longer credits the
v0.24.0 - 2026-08-08
Breaking
- Library surfaces corrected against their upstream pins, so code written to the old shapes stops type-checking until it is updated.
- defmath —
in_triangletakes(x0, y0, arr)with a six-number array instead of eight loose coordinates. - defsave —
saveandsetreturnboolean | undefinedinstead ofvoid, andloadnarrows fromunknownto the same. - druid — the drag callback declares the six parameters the runtime really passes,
(self, dx, dy, x, y, touch), so a handler that readtouchout of the second argument needs its parameter list updated; andlayout.on_size_changed.subscribetakes the inherited event signaturesubscribe(callback, context?), so drop any leading placeholder argument. - gooey — the three dynamic-list calls drop a
root_idargument upstream never took,dynamic_listandstatic_listdrop a trailingis_horizontal, andvertical_scrollbargains upstream'sconfigbefore its callback — so old calls were passing arguments into the wrong slots. - metrics —
create'spositionandcolorare aVector3and aVector4instead ofstring; passvmathvalues, or the module's ownPOSITION/COLORdefaults. - monarch.transitions.easings —
createis gone, since upstream keeps it private; call the per-easingBACK(),BOUNCE(),CIRC()wrappers instead. - nakama — every request-taking call declares upstream's positional parameters instead of a body object, and all 84 retry-capable calls accept a trailing
retry_policyandcancellation_token. The socket surface is gone from this module, which never exported it —create_socketis the one door it opens to a separately vendorednakama.socket. - nakama.engine.defold —
httptakesretry_policyandcancellation_tokenbefore its callback, andsocket_senddrops its third argument. - orthographic —
add_projector,get_projection_id,use_projectorand the constantsMSG_USE_PROJECTIONandORTHOGRAPHIC_RENDER_SCRIPT_USEDare gone; upstream defines none of them, so each already failed or readnilat runtime.world_to_screendrops its thirdadjust_modeargument, which upstream silently ignored. - rendy —
animateandcancel_animationsare gone; usego.animateandgo.cancel_animationsdirectly. - yagames — the five
banner_*calls give way to the sticky-banner API upstream documents (adv_show_banner_adv,adv_hide_banner_adv,adv_get_banner_adv_status), the four sitelock functions are gone because the module never exported them, andpayments_get_catalogtakes upstream's(options, callback).
- defmath —
walljudges a directory by its whole subtree rather than only the sources it directly holds, so a directory whose subdirectories add another kind is no longer eligible. Wall the single-kind directories beneath it instead.
Improved
- Every library's types are now maintained in this repo, forked from upstream where no usable structured source exists: declare the dependency and
resolvematerializes them. Imports and type surfaces carry over unchanged except as noted here.- Reference pages moved — a single-module library now lives at its bare namespace:
/api/nakama,/api/persist,/api/yagames,/api/gooey,/api/bzAnim,/api/platypus,/api/dicebagand/api/rendy. bzAnim's documented import becomesimport * as bzAnim, over the same"bzAnim.bzLibrary"path. - defsave — the previous binding declared about half the module, so the fork adds seven functions (
obfuscate,get_file_path,key_exists,isset,reset_to_default,is_loaded,final), the config fields, andsave'sforceargument. - boom — the pin moves off the
1.0.0tag, which predates the camera helpersto_screenandto_world; both are declared now. - orthographic —
camera.followaccepts an array of game objects as well as a single one, andget_viewandget_projectionreturnMatrix4instead ofunknown. - metrics — both modules gain the module-level
update(),draw()andfps()/mem()calls upstream defines over its built-in singleton, so you can read the FPS or memory figure without creating an instance. - gooey —
gooey.grouptakes theaction_idandactionarguments the runtime requires, so the four-argument call every upstream example writes finally type-checks. - yagames —
player_get_idkeeps a correctly spelled pointer toplayer_get_unique_id, andleaderboards_initis marked deprecated as upstream marks it. - monarch — upstream's README documents the focus listener as
on_focus_change; the function the runtime defines, and the one these types bind, ison_focus_changed.
- Reference pages moved — a single-module library now lives at its bare namespace:
- panthera (
Insality/panthera) joins the corpus: declare the dependency andresolvematerializes a typedpanthera.pantheracoveringcreate_go/create_gui/create,play/play_tweenerand the animation-state shape.defold-tweeneris a runtime companion only — panthera's types resolve without it. - Every forked library is measured against its own upstream Lua on two separately ratcheted axes, functions and constants, so one nobody has checked can no longer read as clean: 35 of the 35 modules now cover their upstream's whole surface on both. Generated libraries carry a committed coverage floor too, so regenerating one can no longer quietly type less of it than before.
- More of each generated library's surface carries a real type where it previously fell back to
unknown.- Callback parameters — arguments documented only as
functionin event, lang and druid are callable types, so you can pass a typed function literal and call the value back without a cast. - Nullable unions — values documented as a union with nil, such as bridge's
platform.idandplayer.name, type asstring | undefined, so a null check is enough. - druid —
druid.button's six style hooks anddruid.drag'sinitcallback name their real parameter types,druid.layout'srowsis adruid_layout_row_data[], and a multi-return call such asdruid.layout.get_content_sizereturns aLuaMultiReturntuple. Component callback fields likeon_clickandon_hoverare event objects you cansubscribeto — declaredefold-eventalongside druid so the type resolves. - log —
get_default_logger_nametakes the realdebug.getinfo()table, so readingshort_srcoff it type-checks. - decore —
ecs.worldreturns a rest tuple you can spread instead of a fixed pair whose second slot was a single anonymousunknown.
- Callback parameters — arguments documented only as
- A library's API reference page shows more of what its types actually say.
- Constants and briefs — a forked library's page documents constants as well as functions: 61 constants gained the description their fork already carried, eleven members were written up in the fork's own words, and 254 members across 14 libraries fall back to upstream's prose under a
Udot marking it as borrowed. - Options shapes — an options object documents its fields instead of rendering as a bare type name — 29 shapes across five libraries, including monarch's
ShowOptionsand gooey'sButtonState. Optional fields are marked?, so an all-optional table no longer reads as all-required. - Deprecations — an upstream
@deprecatedmarker shows as aDeprecatedline carrying its explanation, in the same block the engine pages use. A tag on a type rather than a member reaches the shipped.d.ts, where your editor strikes the name through, but not the page. - Ambient globals — a library declaring most of its surface outside its module block finally documents it: boom goes from 1 symbol to 112 and deftest from 2 to 32. Each is marked
G, and the page's import step notes they are callable without the import.
- Constants and briefs — a forked library's page documents constants as well as functions: 61 constants gained the description their fork already carried, eleven members were written up in the fork's own words, and 254 members across 14 libraries fall back to upstream's prose under a
- The Libraries tree is organized by GitHub origin: a library nests under its owner and the repo you actually install (
britzl/defold-input, notbritzl/in), a repo publishing a single module collapses to one row, and every row spells itsowner/repo/namespacepath out on hover. The maintained-here pin is gone — every library is maintained here now, so it distinguished nothing. wallunderstands nested walls, so you declare one at the boundary you actually mean instead of at every leaf.- Inheritance — a wall on a parent directory that holds no sources of its own narrows every directory beneath it, including subdirectories added later.
- Override — a nested wall fully replaces the one it sits inside, instead of leaving its files in the outer program where
gui.*could type-check inside ascriptwall. - Provenance —
wall --list --jsonreports every narrowed directory withorigin(declaredorinherited) and thedeclaredInancestor that caused it; the plain--listline names the inherited pairs.
- A new
--fail-on-driftflag turns the installed-editor-vs-pin drift notice into a non-zero exit onbuild,watch,run,upgradeandbob build/bundle/run, so CI stops passing on a warning nobody reads. The notice text and--jsonpayload are unchanged, and a command that already failed keeps its own exit code. - The agent runbooks warn that the script lifecycle factory needs a value import — the
import typeplusdeclare constform buildsok: truewhile leaving the hooks unerased — and route Defold's resultingFORMAT_ERRORresource cascade back to that fix.
Fixed
- Forked libraries declare members their upstream really defines that the previous bindings left out.
- yagames — 22 members covering whole feature areas: the events API, the multiplayer-sessions trio, the five
features_*calls, fiveplayer_*getters, the shortcut-prompt pair,flags_get,is_available_method,server_timeanddevice_info_is_tv. - nakama — 16 members: the subscriptions area, the cancellation pair
cancellation_tokenandcancel, plusdelete_accountanddelete_tournament_record. Its 12 enum constants are declared too, typed as their literal values soop === nakama.APIOPERATOR_BESTnarrows. - gooey —
is_enabled,acquire_input,release_input,create_theme,mask_text,radiogroup,horizontal_scrollbarandset_focus. - monarch — the seven live message hashes (
TRANSITION_*,FOCUS_GAINED,FOCUS_LOST) andregister, upstream's alias ofregister_proxy. The groupedTRANSITIONandFOCUSobjects offered instead are now marked deprecated, as upstream marks them. - monarch.transitions.gui — the twelve transitions are declared as functions rather than constants of an opaque callable type, so the page documents each one's arguments.
- orthographic —
get_automatic_zoomandset_automatic_zoom, plus theMSG_SET_AUTOMATIC_ZOOMmessage that does the same by post. - rendy —
camerasplusdisplay_width,display_height,window_widthandwindow_height. Upstream advises against manipulating these directly, which each one's doc-comment now says. - metrics — both modules expose the drawing defaults
POSITION,COLORandFORMAT, used for anycreateargument you omit. - dicebag —
bagsandtables, the keyed state everybag_create/table_createwrites into and every draw reads back. - defcon —
register_moduletakes upstream's optional secondnameargument, and the module exposesprint,pprintandserver. - platypus —
SEPARATION_RAYSandSEPARATION_SHAPES, the two values forcollisions.separation. - bzAnim —
setMaxPoints,registerControllerandunregisterController. - richtext.color —
parse,parse_hexandparse_decimal; nakama.util.log —customandformat; persist —exists.
- yagames — 22 members covering whole feature areas: the events API, the multiplayer-sessions trio, the five
- A dependency that ships modules across two of this repo's registry lanes now resolves and materializes every module;
resolvepreviously kept only the first lane's module and silently dropped the rest. - The explicit type-argument factory form the script lifecycle guide documents —
export default defineGuiScript<MenuSelf>({ … })— builds to its component file (src/menu.ts.gui_script) instead of falling through to a plain.luamodule of the wrong kind, and a type-only name imported alongside the factory (import { defineGuiScript, type Hash }) no longer fails the build with an unresolvablerequire. The scaffolded agent contract matches: both self-typing forms work. - go and msg document the overloads the toolchain actually ships, each row carrying the description and parameter table its own call shape takes:
go.getandgo.setlead with their curried property-key generic,go.propertylists its eight typed forms,msg.postits two andmsg.urlits three. The committedllms-full.txtcarries the same forms. - TypeScript vs Lua no longer suggests a sufficiently pure npm package can work, and TypeScript gotchas gains an entry with the exact build failure, why
node_modulesis never read, and how to vendor the source undersrc/instead. - A library whose types are generated from its README reads an argument bracketed across a comma (
data [, overwrite]) or through an escaped bracket (duration \[, scaler]) as optional rather than required, and marks every argument inside a multi-argument group optional. - A library reference page with a dotted namespace, such as monarch.transitions.easings, titles itself
britzl/monarch/monarch.transitions.easingsagain — matching its Libraries card — instead of repeating the namespace twice with the author dropped, and its heading wraps at the dots rather than scrolling the page sideways. - narrator's
Story.observecallback parameter is namedvalue, after the argument the library actually passes it. - A documentation source can no longer replace a library's existing types with a weaker surface: a source documenting no parameter or return types, one whose comparison surface was truncated, and one hidden behind a single exported handle were all scoring as clean matches. persist and yagames keep the types they had.
v0.23.0 - 2026-07-27
Breaking
- More libraries' types are now maintained in this repo — each regenerated from its upstream source through the shared LuaLS / ref-doc pipeline (as with druid and decore) and marked with the maintained-here pin in the docs; each surface now follows upstream, so it differs from the previous hand-written binding.
- tweener (
Insality/defold-tweener, tag6) — per-easing helpers are no longer module-level constants. - bridge.bridge (
Playgama/bridge-defold,v2.0.0) — regenerated from its committed.script_apias an importabledeclare module. - event (
Insality/defold-event, tag19) — the former untypedanypassthrough now carries real types (event.create, subscribe/trigger, promise and queue instances). - lang (
Insality/defold-lang, tag5) — the twelve typed functions are tightened, andload_langs, the state getters, and typedlang.data/lang.stateare added. - log (
Insality/defold-log, tag6) —get_logger's name argument is now optional and its forced-level argument a plainstring, and the logger's level methods now require theirdataargument. - proto (
Insality/defold-proto, tag1) —get/decode/verifyreturn the nativeLuaTable,set_loggertakes a typedproto_logger, and the full encoding API is surfaced. - saver.saver and saver.storage (
Insality/defold-saver, tag8) —init,save_game_state,get_save_path, andset_loggertake their typed optional arguments and the full save and key-value storage APIs are surfaced. - immutable (
paweljarosz/lua-immutable, tagv1.1) —makereturns the typedImmutableinterface rather than a genericReadonly<T>. - squid (
paweljarosz/squid, tag1.2) — the previous binding typed onlysave_logs/get_config().is_enabled; the surface now exports the module log-level constants and logging API, a typedget_config/SquidConfig, and a typedSquidInstancefromnew(). - narrator (
astrochili/narrator, tag1.8) — replaces the hand-written passthrough with the upstream parser plus theNarrator.Storyruntime API, made runtime-faithful:parse_contenttakes itsinclusionsargument optionally,continue()returns a single paragraph or an array of them, and the internalObject/constructortables no longer leak into the surface.
- tweener (
Improved
- The editor-scripting authoring path is now documented: a Core-concepts guide page walks through
defineEditorScript, the<name>.ts.editor_scriptartifact, and the editor's auto-load discovery, with a worked custom-command example. - LuaLS library types (druid, decore, tweener, event, lang) now emit every nil-bearing trailing argument — both
T | nilunions and type-suffixT?params — as optional, and nilable interface fields (function | nil,string?) as omittable object properties. Faithful upstream calls likeevent.create(),instance.subscribe(cb),lang.set_lang("en"),lang.set_next_lang(), andlang.init([{ id, path }])now type-check instead of demanding an explicitundefined, and object literals may drop fields likeloaderthey faithfully omit. Event and promise instances are also callable now (instance(payload)), matching their runtime__call.
Fixed
- Installed packages can now resolve the bridge.bridge library again — its script_api resolve manifest was missing from the published tarball, so the
resolvecommand silently droppedbridgeon a real install. - A script_api library whose types reference engine handles (Hash, Vector3, Url, ...) now emits an importable
declare moduleinstead of a broken module augmentation, soimport { ... } from "<library>"resolves instead of failing withTS2307. - LuaLS library types (druid, event, log, tweener) no longer leak non-public members: fields and methods marked
@private/@protected/@package(and methods marked@local) are hidden from the generated declarations, the/apidocs, and the fidelity report alike, so the three surfaces describe one identical public set. For example theloglogger drops_last_gc_memory/_last_message_time/format/log, and druid components drop the base's protected lifecycle hooks andget_uid. - A dependency that ships several modules from one repository (for example defold-saver's saver and storage) is now fully handled: the
resolvecommand materializes every module instead of keeping only the first, and the docs-site Libraries navigation groups them into a single entry instead of one per module. - The LuaLS front-end now reliably infers a constructor's return type and instance methods when the function-local class declares extra locals, and a stale
---@type fun(...)method annotation no longer attaches across intervening lines to a later member key — a latent mis-emit fixed before any maintained library shipped it.
v0.22.0 - 2026-07-24
Added
- Editor scripts are now recognized and built: a source that does
export default defineEditorScript({ get_commands, ... })compiles to a<name>.ts.editor_scriptreturning the hooks table the Defold editor loads — mixing anEditorCommandtype import with the factory erases cleanly (no strayrequire), and editor-only directories are never offered as per-kind type walls. The typededitor.*API and project scaffolding land in follow-ups.
Improved
- The repo-maintained-library marker in the API reference is now green and easier
to spot: in the sidebar it sits on each library namespace leaf instead of the
parent folder row, and it also appears on the
/librariesindex cards.
Fixes
initnow scaffolds the.gitattributesthe Defold editor emits (linguist overrides for correct GitHub rendering and language stats) and ignores WindowsThumbs.dbalongside.DS_Store. Both merge into existing files on upgrade, so an editor-created project gains only what it was missing.initnow writes a.defignoreso the Defold editor and bob skipnode_modules,.defold-types, and.vscodewhen scanning for resources. It merges into an existing file, keeping any lines you added.
v0.21.1 - 2026-07-21
Improved
- The
upgradeguide page is now a CLI verb page (toc-title: upgrade,# Upgrade) sitting in the CLI sidebar subgroup right afterinit.
Fixes
- Applied Biome's current formatting rule to inline type literals in the guide-docs test, clearing the lint gate after a formatter-rule update.
v0.21.0 - 2026-07-20
Added
- Typed bindings for LuaLS-annotated pure-Lua libraries.
defold-typescript resolvenow materializes generated.d.tsfor libraries such as:- Druid
- Decore (first two libraries to proof concept)
Dependencies — generics, inheritance, variadics, and multi-returns preserved — each with a rendered API page at
/api/<name>, and the new Authoring LuaLS library types guide covers adding further libraries as a config-only change, including how to fill an empty API-page description. - Library reference pages and the sidebar Libraries tree both show a map-pin marker beside libraries whose type bindings this repo maintains (Druid, Decore), with a hover hint, so you can tell them apart from vendored libraries at a glance.
v0.20.8 - 2026-07-19
Added
- In progress: typed bindings for LuaLS-annotated pure-Lua libraries (starting
with Druid). The plumbing is landing release by release — source ingest and
the LuaLS-to-TypeScript type mapper are in place, with the mapper now emitting
valid TypeScript for vararg parameters and function return unions; the
generated library
.d.tsyou import ships in a later release.
v0.20.7 - 2026-07-18
Added
- Guide pages for the
runandbobcommands, covering the launch/build workflow, the tworunresolver errors, thebob.jarcache, and the per-subcommand--jsonshapes. - A pre-commit gate that fails any commit not staging a change to this
changelog, so it can no longer drift behind the work that lands; bypass a
genuine exception with
git commit --no-verify.
Fixed
bob statusnow honors the--java/DEFOLD_JAVAoverride, matching executing Bob commands, so the preflight reports the same Java runtime a build will actually use.
v0.20.6 - 2026-07-18
Fixed
- Cutting a release now refreshes the published
/changelogon its own: the new tag's date replaces- Unreleasedfor the shipped version without a manual docs redeploy.
v0.20.5 - 2026-07-18
Improved
- The installed-editor pin-drift notice now covers
watch,run,bob, and theupdatealias, warning when the editor you have open drifts from the project's version pin.
Fixed
runderives its project directory from the arguments before--, so pin drift is no longer read from a<cwd>/--path.
v0.20.4 - 2026-07-17
Improved
- Defold-pin drift checks are unified under a single
verify-docs-driftmise task, with the drift-root split from the evidence-root so staleness is the sole trigger. - Release-smoke overrides derive from the CLI manifest, with a pinned TypeScript.
v0.20.3 - 2026-07-16
Added
bump:defoldorchestration command for Defold version bumps, including an offline--checkrelease-evidence gate.regen:allaggregate regeneration command.set-targetverb to write thedefold-targetpin.- A docs-site color-token parity drift guard.
Improved
--defold-targetnow notifies when it overrides a livepackage.jsonpin, and points the override notice atset-target.resolveprunes orphaned extension version-pins.
v0.20.2 - 2026-07-14
Fixed
- Opaque signature deep-link hrefs now respect the deploy base path.
v0.20.x
The API reference moved to a combined, multi-version surface and the upgrade
verb landed.
Breaking
- The
/apiroute domain is inverted: the combined multi-version surface now owns the canonical/api, each tracked version gets an explicit/api/defold-<version>family, and the previous/api/combined/*routes arenoindexcompatibility redirects.
Added
upgradeverb (withupdateas a synonym): resolve the latest toolchain, then hand off to the newer CLI or re-scaffold in process, captured under--json. A new upgrading guide documents it.- Combined union API surface with an N-version availability model, a version
selector, a declaration-backed
api-signaturesartifact, and combined-only availability badges. - Defold 1.13.0 type surface promoted, with a deterministic release importer, an
offline release-readiness gate, a 1.13.0 upgrade guide, and catalogued 1.13.0
deprecations (camera-focus messages,
reset_constant) surfaced via@deprecated. --help/-h, top-level and per command.
Fixed
- nil-bearing engine returns are typed as
T | undefined, and the nil-return truthiness guidance is corrected to~= nil. - Every promise derived from a captured spawn settles, so an unspawnable child leaves no orphaned rejection.
v0.19.x
Added
initwrites the agent contract (AGENTS.md), re-syncing an existing one only under--force.
Improved
llms-full.txtinlines guide bodies with web chrome stripped and headings nested under## Guide.- Scaffold commands survive a broken toolchain via lazy-loaded transpiler dispatch verbs.
Fixed
- Refuse to re-release a commit that already carries a release tag.
- Pin
typescript@6.0.2in the scaffold and cap thetstl-pluginpeer below the TS7 native port.
v0.18.x
Added
- Vendored native and pure-Lua library types materialized into
.defold-typesduringresolve, with/apidocs pages grouped by author, a Libraries nav tab, and a live-fetch drift gate; thelibrary-typespackage is published. - Covariant vmath functions typed with generics, so same-type-in yields same-type-out.
Improved
initmerges into an existingtsconfig.jsoninstead of clobbering it and reports per-file operations.watchstays alive through startup compile errors with located highlighting, and build failures surface located, one-per-error source positions.
Fixed
initnever excludessrc/main.tsand self-heals a tool-added exclude on merge.- The CLI node-runtime spawn crash; Java resolution falls back to the editor's
bundled JDK when running
bob.
v0.17.x
Added
- More vendored library types (persistence, text and narrative, platypus, defold-event, input, monarch), a pure-Lua classification manifest, and a library-types drift gate.
types.is_*checks emitted as user-defined type guards.
Improved
- The API overview replaced tables with cards, then a linked signature list.
- Lua
type()return tightened to its closed string union.
Fixed
- Upgraded the GitHub Pages deploy actions off deprecated Node 20.
- Long space-less inline code wraps on narrow screens instead of scrolling.
v0.16.x
Added
- Canonical JSDoc for the six core value types, a typed-messages guide page, a
previous/next pager on every article, and shiki line-highlighting plus
[!MORE]tap-to-reveal disclosures in the Tetris tutorial.
Improved
- The Tetris tutorial is inverted into inline walkthroughs with the full script collapsed into a disclosure.
- Global-type docs render as markdown from their JSDoc.
Fixed
- The scaffold declares a direct
lua-typesdevDependency so Lua stdlib globals resolve. - Scaffold
.gitignorelines match Defold's canonical/buildand/.internalform.
v0.15.x
Improved
- Several mise tasks ported to shell-free Bun scripts (release-pack-proof,
current-version,
dev:slides). init --forcemigrates a deprecatedbiome.jsonto the preset.
Fixed
- Tetris tutorial file-create and scene-wiring steps, plus a window-size step so the board centers.
ScriptPropertiesOfexported from the barrel.
v0.14.x
Improved
- The docs renderer supports same-line GitHub alert markers, and wide tables scroll.
Fixed
- Migrated
biome.jsonoff deprecatedrecommendedto the preset (Biome 2.5.1).
v0.13.x
Added
- The Build Tetris tutorial guide page and its runnable example under
docs/examples, code-block filename chips from atitle=fence, and a loadable scaffoldedgame.projectwith a[bootstrap]collection and input binding.
Improved
- The scaffold no longer enforces
noDoubleEquals;===and==compile to identical Lua, and the guidance is reframed accordingly.
v0.12.x
Improved
- Data-structures guide: Lua table extensions documented,
LinkedListdropped.
Fixed
sourceMappingURLis kept as the generated file's last line.- Full builds prune kind-switch outputs and warn on sourceless orphans.
v0.11.x
Breaking
- npm publishing moved to CI OIDC trusted publishing; local
bun-publishis retired.
Added
- The docs API version selector, with per-version
/apiroutes and search indexes, global value-type reference pages, the offlinellms.txtknowledge pack, and topical Defold-way agent runbooks. - Signature override stores for the Lua standard library (
string,table,os,math,io,socket, and the rest), with an AST drift guard.
Improved
- Releases require CI green before publish.
- A responsive docs-site topbar and a collapsible sidebar drawer.
Fixed
- A Windows separator leak in the client graph.
- GitHub-compatible heading slugs so in-page anchors resolve.
v0.10.x
Added
- A top-of-page function summary table on
/apipages. - A presence-parity gate enumerating
ts-defold-types-only symbols. - Socket handle methods emitted as receiver interfaces.
Improved
- Lifecycle-hook and
InputAction/InputTouchmembers documented with fixture-pinned JSDoc.