Skip to Content
defold-typescript
Get startedGuidesAPILibraries
Project configuration

Typing native extensions

Defold native extensions ship their own Lua API alongside the engine's. When a project depends on an extension, defold-typescript resolve reads that extension's .script_api docs and generates a TypeScript module for each namespace they declare — the same fan-out the built-in engine namespaces (go, vmath, …) go through, applied to whatever extensions your project actually declares. The generated surface lands in a project-local, gitignored .defold-types/ package, so extension functions gain autocomplete and tsc coverage behind one import.

No extension is typed until it is resolved. That includes the ones Defold maintains, such as iap, iac, push and webview: @defold-typescript/types declares only the engine, so import * as iap from "iap" is a type error until the project depends on extension-iap and resolve has run.

Declaring an extension

Extensions are declared in game.project under [project], one archive URL per numbered dependencies#N key — the same INI surface the Defold editor's Fetch Libraries writes:

[project]
title = My Game
dependencies#0 = https://github.com/defold/extension-iap/archive/main.zip
dependencies#1 = https://github.com/some/asset-pack/archive/main.zip

resolve reads every dependencies#N URL under [project]. A game.project with no [project] section is an error; a [project] with no dependencies#N keys reports no extension dependencies declared and exits cleanly.

Materializing the types: resolve

The resolve command reads every dependencies#N URL, downloads and caches each archive, and emits one @globalTable module per .script_api doc into .defold-types/extensions/, wiring it into tsconfig.json:

bunx @defold-typescript/cli resolve

Run it once after declaring a dependency, and re-run it (or leave watch running, which re-resolves on every game.project save and every Fetch Libraries) whenever you edit the dependencies#N keys. See Resolve for the full behavior, the --frozen lockfile mode, version pinning, and the cache location.

Consuming the generated namespace

Import each namespace under any local name. The build turns the import into a local alias of the extension's global, so no require reaches the Lua:

import * as iap from "iap"; // local iap = _G.iap

iap.set_listener((self, transaction, error) => {
  // transaction and error are typed from the extension's .script_api
});

tsc picks the surface up through the "extensions" entry in compilerOptions.types. A dotted namespace imports by its full name, as in import * as cmd from "rive.cmd". The namespace is not a global: a bare iap.set_listener(...) with no import fails with Cannot find name 'iap'.

Extensions that extend an engine namespace

An extension's docs are not limited to a namespace of its own. A .script_api whose top-level name is an engine namespace adds its members to that namespace rather than replacing it, so the engine's members and the extension's sit side by side on the same object. Such a doc stays ambient, with no import, because a module cannot add members to the engine's global.

extension-spine is the worked example: it ships three docs, giving one new spine namespace plus additions on the engine-owned gui and resource.

const node = gui.get_node("spineboy");

// From the extension's spine_gui.script_api.
gui.set_spine_skin(node, "default");

// From the engine — same namespace, same node handle.
gui.set_position(node, vmath.vector3(0, 0, 0));

The handle types line up because the materialized surface imports its branded engine types from the published @defold-typescript/types/core-types entry, so an extension's Opaque<"node"> is the very same type gui.get_node returns.

Module-form native extensions

A hand-authored or shipped declaration can type a native extension as a module (declare module "<id>") instead of an ambient namespace, so projects import it. A native extension registers a global table rather than a Lua module, so the declaration must carry @globalTable:

/** @globalTable */
declare module "pixels" {
  export function fill(color: number): void;
}

Every import of the module then compiles to a local alias of the runtime global — never a require:

import * as pixels from "pixels"; // local pixels = _G.pixels
import { fill } from "pixels"; // reads the same global

Without the tag, a bare declare module makes the build emit require("pixels"). The build leaves that path as written (there is no Lua source to resolve it to), and the Defold engine then fails to load the script, because the extension registered a global, not a module. The tag's argument names the global when it differs from the module id (/** @globalTable b2d.body */); a tag naming an invalid Lua global fails the build with an error giving the file and line.

resolve writes this form: the declarations it generates from .script_api docs and the curated native extensions it installs are @globalTable modules, so a project writes import * as iap from "iap" to reach iap and import * as daabbcc from "daabbcc" to reach DAABBCC.

Browsing Defold's own extensions

The extensions Defold publishes on GitHub have reference pages under Libraries › defold, one per .script_api doc, such as iap and spine.gui. The defold section is listed first, in the sidebar and on the Libraries page, and marked (official) so it reads apart from community libraries. Each page shows the pin it was read from — the latest release, else the newest tag, else a commit. A release or tag pin also names the Defold version that was current when it was cut, as a hint about its age, not a promise that it works with that version. That pin only fixes what the page shows: which version your project depends on is still your choice in game.project, and resolve types whichever one you pick.

Defold libraries that ship no .script_api have pages there too, such as extension-qrcode and asset-pbr. Their sidebar entries and cards are marked with a no-typed-API icon. Each page describes what the library ships and whether it registers a Lua API that is simply not typed, then shows the same GitHub pin and numbered setup steps as a typed library page: add the dependency at that pin, then the library's own steps. Two kinds of repo depart from that. A placeholder repo with nothing in it yet, such as extension-playintegrity, has no install step. A repo upstream asks you to fork, such as extension-prometheus, starts with forking it and depending on your fork. resolve still reports each one as asset-only, skipped.

Libraries on the Defold Asset Portal that ship a .script_api have reference pages under their GitHub owner, one per doc, such as defos and astar. Each page is read from the doc at the pin the portal survey recorded, gives the dependency step for that pin, and links the library's Asset Portal entry. A doc with no description of its own leads with the portal's. resolve types these libraries from your dependency like any other extension.

Portal libraries that ship no Lua API, such as shaders, materials, sounds and editor scripts, are listed the same way under their GitHub owner, such as defold-sharp-sprite. Each page leads with the portal's description of the library, gives the dependency step for its pin, and links its Asset Portal entry. On both kinds of portal page, a release or tag pin also names the Defold version that was current when it was cut, the same hint Defold's own libraries carry.

For the command itself — --frozen, version pinning, drift detection, and the cache location — see Resolve.

Library page addresses

A library page's address names the repo the library comes from. A typed library's API page is /api/<host>/<owner>/<repo>/<namespace> and an untyped library's listing is /libraries/<host>/<owner>/<repo>, all lowercase. <host> is the forge the repo lives on (github.com, codeberg.org) and <owner>/<repo> is the repo there, so the same owner and repo on two forges are two libraries with two addresses. <namespace> is the module the page documents, so a repo that ships several modules has several pages: defold/extension-spine/gui is one of extension-spine's. The repo in the path also keeps apart two libraries that ship the same module, such as the two mpeg pages, defold/extension-videoplayer-mpeg/mpeg and morgerion/defold-mpeg/mpeg.

On this page