Skip to Content
defold-typescript libraries
Guides

Authoring LuaLS library types

Some pure-Lua Defold libraries ship their own type information as inline LuaLS (---@) annotations rather than a .script_api. This toolchain prints TypeScript declarations for them from those annotations, so a consumer that declares the library gets autocomplete and tsc coverage with no hand-written .d.ts. resolve prints the declaration into the consumer's project from the library version it depends on, or from the sources pinned in library data.

Adding such a library is data, not code: you add one entry to the luals list of the library's recipe.json, in its folder under the library data folder (the newest version-named folder under packages/library-types/data/; the library folder also holds the fetched sources under source/), run the three generation commands, check the emitted API-doc description, and commit the library's files and its artifacts. There is no pipeline source to touch — the same front-end that produces the druid types produces yours.

This page is for library-type authors. Library data lives in the toolchain repo under packages/library-types/data/, so you add or change a library with a pull request there, not to defold-typescript/library-data. If you only want to use a vendored library in your own game, you need nothing here — just declare the dependency and run resolve.

The bun commands on this page run from the toolchain root. Each tool reads and writes the library data under packages/library-types/data/ and writes its reports to api-doc/ and fidelity/ in packages/library-types/.

Is your library a LuaLS target?

Two facts decide it:

  • It is plain Lua (installed via Defold's Fetch Libraries, no .script_api), and
  • its source carries inline ---@ annotations — ---@class, ---@field, ---@param, ---@return on the public module.

A hand-written library with no annotations is not a LuaLS target; those are maintained as hand-vendored .d.ts forks. A library whose annotations are sparse (near-zero fidelity coverage, see below) will emit a hollow surface and is not worth adding.

The library's runtime require path (its moduleId) must not already be claimed by another library in library data — two front-ends emitting the same module would collide.

1. Add a recipe.json entry

Start with library add, which writes the folder below from the archive URL, with a starting luals entry and the sources it reads:

bunx @defold-typescript/cli library add https://github.com/owner/mylib/archive/refs/tags/1.2.3.zip --data packages/library-types/data

Then edit recipe.json by hand: add typeRenames and externalTypes for the tokens the library's annotations leave unmapped, narrow sourceGlobs and ignore, and add an entry for each other module the library exposes. The tables below describe every field.

Each library pins its own repository and tag — a LuaLS library ships no .d.ts, only annotations, and each lives in its own repo at its own release. Its folder is named for the repository: its <host>/<owner>/<repo>, lowercased, without .git (https://github.com/Insality/druid is github.com/insality/druid/). The folder pins the library once:

FileFieldRequiredWhat it is
library.jsonrepoyesThe GitHub repository URL, e.g. https://github.com/Insality/druid.
library.jsonlicensenoSPDX-style license id, surfaced by the library page's provenance block. Defaults to "".
library.jsonrefKindno"tag" or "commit" when upstream publishes no stable release (GitHub's latest release skips prereleases), so the docs page's adopt step names the pinned archive instead of linking a releases page. Omit it for a repo with releases.
reviewed.jsonrefyesThe exact release tag to pin. Resolve the newest stable tag (git ls-remote --tags <repo>) — never invent one.

Each generated module is one entry in recipe.json's luals list:

FieldRequiredWhat it is
sourceGlobsyesGlobs selecting the .lua files to snapshot, relative to the repo root (e.g. ["druid/**/*.lua"]).
moduleIdyesThe library's runtime require path, dotted (e.g. druid.druid). This names the emitted declare module and scopes the module-function surface to <moduleId-as-path>.lua.
namespaceyesThe artifact stem — the emitted files are fidelity/<namespace>.json and api-doc/<namespace>.json. The fetched sources sit under the library folder's source/<namespace>/.
typeRenamesnoMap from a LuaLS type name to the TypeScript type text to emit (e.g. { "vector3": "Vector3" }). The value is emitted verbatim and may name an ambient global, including a dotted one like debug.FunctionInfo — it never contributes an import. Omit or {} when the library references no renamed types.
ignorenoGlobs excluded from sourceGlobs — tests, examples, editor widgets. Defaults to [].
externalTypesnoMap from a type name another target owns to { "module": "<its moduleId>", "name": "<its export>" } — see below. Omit when the library references no other library's types.

A missing required field fails loudly, naming the field, the offending entry and its recipe.json.

Types another library owns

A library that requires a second library annotates the borrowed type by its bare name (druid's ---@field on_click event). Left alone that token resolves to nothing local and lowers to unknown. Naming its owner in externalTypes instead makes the emitter write a real import at the top of the declare module block and resolve every use of the token to it:

"externalTypes": { "event": { "module": "event.event", "name": "event" } }

emits import type { event } from 'event.event';, types all 46 of druid's callback fields as event, and resolves the ---@class event.on_size_changed: event parent to a real extends. The import is type-only, so it binds no value and a library that exports a function of the same name (quest.event) still compiles. The key is the LuaLS token as written; module must be the owning target's moduleId exactly, and name its exported type. A token whose local name would collide with one the library declares itself fails loudly rather than silently shadowing it.

The consuming project must declare that upstream library too. resolve builds no inter-library dependency graph, so a project that lists druid alone gets druid.druid without event.event — the import then degrades to an error-any under the repo-wide skipLibCheck. Declare both; druid does not run without event.event at runtime either. quest and token import event from event.event the same way (quest also imports queue), so a project that lists either one declares defold-event beside it.

Prefer externalTypes over a typeRenames entry pointing at an import(...) type: the api-doc lowering maps through the same context, so an inline import('event.event').event would render as the user-facing signature on the library's /api page, where externalTypes renders the clean event.

A runtime require is not by itself a type dependency, so decide from the annotations rather than the requires. panthera opens panthera/panthera.lua with local tweener = require("tweener.tweener"), yet no annotation in its subtree names a tweener type — every easing is annotated string|constant. It therefore takes no externalTypes entry, and a project consuming panthera needs defold-tweener installed for it to run but not for its types to resolve — the inverse of druid, which needs event.event for both.

Types the Lua stdlib already owns

Some tokens belong to no target at all — the ambient Lua standard library already declares them. log's ---@param debuginfo debuginfo names the table debug.getinfo() returns, which lua-types types as debug.FunctionInfo. That takes a typeRenames entry, not an externalTypes one:

"typeRenames": { "debuginfo": "debug.FunctionInfo" }

The emitted signature reads debuginfo: debug.FunctionInfo with no import line, and the log page renders that same dotted name — the way Vector3 and Opaque<"node"> already render there.

The rule: a token another target owns takes externalTypes and gets an import; a token the ambient stdlib already declares takes a dotted typeRenames value and gets none. A library that declares the token itself wins over either, so a rename never shadows a real local declaration.

Two naming rules keep such a local declaration from hiding the type a rename names, and both apply with no configuration. An alias that names itself in its own body means the type it shadows: ---@alias hash userdata|hash emits type hash = Opaque<"userdata"> | Hash, and every other hash in the library still names the local alias. A declaration named like a core or typeRenames value is declared with a trailing underscore: ---@alias Url url|string emits type Url_ = Url | string, the library's own Url references read Url_, and an engine url still reads Url. Two declarations that land on one generated name, such as Url beside the library's own Url_, fail the emit naming both.

Where an upstream annotation restates a member it inherits from such a parent, and restates it incompatibly enough that the emitted redeclaration would not type-check, drop the restatement with an annotationOverrides field override — "fields": { "subscribe": { "drop": true } } — and let the member inherit. Like every override, a drop naming an absent field throws rather than passing silently.

The second drop shape is a class-level @overload. The emitter lowers one onto the interface as a call signature, which is right whenever the class really is callable — event's EVENT_METATABLE and PROMISE_METATABLE each carry a real __call. It is wrong where the @overload describes the module table while the interface types the instance: log reuses one table as both, but only the module table gets __call, and get_logger returns an instance built on { __index = M }, which Lua never treats as callable. Drop that signature with "callSignature": { "drop": true } on the interface. Same loud failure as the others: an override naming an interface that has no call signature throws.

Some libraries bind a ---@class to a field of the module table instead of declaring a ---@field for it: token writes ---@class token.event.on_token_change: event directly above M.on_token_change = event.create(). The class becomes an interface, but nothing exports the value, so token.on_token_change would not exist in TypeScript. A moduleObject override names the module's class and each bound field with its class:

"annotationOverrides": {
  "moduleObject": {
    "interface": "token",
    "fields": { "on_token_change": { "type": "token.event.on_token_change" } }
  }
}

Each field emits as export const on_token_change: token_event_on_token_change;, documented with its class's description, and the module's own class is no longer emitted as an empty interface. The override throws when the module class or a field's type is absent from the model, when the module class already declares the field (upstream added the ---@field, so delete the entry), when a module function has the same name, and when the parser already treats a different class as the module object.

Other libraries assign constants to the module table with no annotation at all: live-unbundler writes M.MSG_ALL_LOADED = hash("all_loaded") and M.RES_BOTH = 3 at the top of its module file, so the lane exports neither. A moduleConstants override types each one with a LuaLS token and an optional doc line:

"annotationOverrides": {
  "moduleConstants": {
    "MSG_ALL_LOADED": { "type": "hash", "doc": "Sent when every requested module has loaded." },
    "RES_BOTH": { "type": "liveupdater.res_mode", "doc": "Download both resolutions." }
  }
}

Each entry emits as a documented export const MSG_ALL_LOADED: Hash; and appears on the /api page, and its token counts toward the fidelity report like any annotation. Only a column-0 M.NAME = ... on the table the module's own file returns (return M) counts as an assignment, as does the first target of M.DEBUG, M[1] = 1, "DEBUG"; an assignment on another table, such as Other.NAME = 1, does not. The override throws when the returned table never has the name assigned at column 0, when a module function has the same name, and when the module object's class already declares it as a field.

A ---@meta file can describe a class's functions with dot syntax: ads-wrapper's ads_networks/ads_network.lua starts with ---@meta, puts ---@class ads_network on local ads_network = { NAME = "ads_network" }, and then annotates function ads_network.setup(params) and its siblings. When the tag is the file's first non-blank line, each such function becomes a method of ads_network declared with this: void (setup(this: void, params?: unknown | undefined): void;), because callers invoke it as network.setup(params), not network:setup(params). In any other file the same form stays a module function, since a runtime module may annotate its own table as a class and still export its functions.

A dot function on another local table belongs to that table when the returned module re-exports it at column 0. flow's flow/flex.lua defines function Node.new(opts) on local Node = {}, assigns FL.Node = Node, and ends with return FL, so new is declared on export const Node: { "new"(this: void, ...): Node }, not as a top-level flex.new. Because the file also sets Node.__index = Node and Node.new declares ---@return Flow.FlexNode, the Node interface extends Flow_FlexNode, and new plus every method annotated ---@return Flow.FlexNode self return Node, so flex.Node.new({ key: "root" }).set_width(960).calculate_layout(960, 640) keeps the chainable methods. A table exported under several fields is declared under each field. A field assigned more than once declares the table it is assigned last.

Where an annotation types a parameter wrongly, a type token on a moduleFunctions parameter replaces it: ads-wrapper's queue.lua writes ---@param fn ads_callback, though run calls fn(network, callback, params), so the ads_wrapper.queue target retypes it:

"annotationOverrides": {
  "moduleFunctions": {
    "add": {
      "params": {
        "fn": { "type": "fun(network: ads_network, callback: ads_callback, params?: table)" }
      }
    }
  }
}

add then emits fn: (network: ads_network, callback: ads_callback, params?: LuaTable) => void. A parameter of interfaces.<name>.methods.<method>.params takes the same type key. Naming an absent function or parameter throws.

"optional": true on interfaces.<name>.methods.<method> emits the method as name?(...), for a method the library checks for before it calls it. ads-wrapper's wrapper.lua guards the call with if network.request_idfa then, so the ads_wrapper targets mark ads_network.request_idfa optional, and a network without it still passes ads_wrapper.ads_wrapper.register_network.

2. Generate the artifacts

Run the three commands from the toolchain root, in order. Each iterates every LuaLS target in library data, so an unchanged entry re-emits byte-for-byte and only your new entry produces new files.

# snapshot the pinned sources into <library>/source/<namespace>/
bun packages/cli/src/library/sync-luals-types.ts --fetch --data packages/library-types/data
# build fidelity/<namespace>.json — the coverage report
bun packages/cli/src/library/sync-luals-types.ts --fidelity --data packages/library-types/data
# check library data, then lower api-doc/<namespace>.json — the site's model
bun packages/cli/src/bin.ts library check --data packages/library-types/data --api-doc-out packages/library-types/api-doc
  • --fetch reads the pinned tree, applies sourceGlobs minus ignore, and writes each selected .lua under <library>/source/<namespace>/, preserving tree shape. This is the only command that touches the network; everything after it reads those committed fixtures, so the pipeline is reproducible offline.
  • --fidelity parses the fixtures and reports how much of the surface resolved to a known type (see below).
  • resolve prints the .d.ts a consumer sees from these fixtures, or from the dependency's own archive. Interfaces and aliases come from the whole snapshot; the module's own functions come only from the moduleId file.
  • --api-doc-out makes library check lower the same model, once its checks pass, to the JSON the /api page renders.

A ---@deprecated before a ---@class, ---@alias, or a function declaration carries into both artifacts — as a JSDoc @deprecated in the .d.ts and as a Deprecated line on the /api page, with the tag's own text when it has any. A tag on a type still reaches only the .d.ts, since a type has no page heading of its own to carry the line. Only the strict ---@deprecated form is read; a spaced --- @deprecated is treated as prose, as it is for every other tag.

3. Read the fidelity report

fidelity/<namespace>.json tells you whether the emit is worth committing:

  • coverage — the fraction of type tokens that resolved to a known type. Druid sits around 0.9; a healthy new library lands in the same range. Near-zero means the source is not meaningfully annotated — reconsider the target.
  • unknownTokens — the distinct type names that fell back to unknown. A cross- library reference (another Insality module) shows up here until you name its owner in externalTypes, which resolves it; the LuaLS placeholders _ and a bare ... are not among them, because they declare no type and now lower to unknown without counting against coverage, and neither is a bare function, because it now lowers to the callable type (...args: any[]) => unknown. A rename that should have applied shows up as an unexpected entry — fix typeRenames and re-emit.
  • undocumentedMembers — members with no annotation at all; informational.

Each report's coverage is pinned by a committed floor, the module's entry in floors in the library's library.json, so a regeneration that lowers it fails the suite instead of quietly rewriting the report, and library check measures the module against the same floor. Regenerating never touches the floors; when you genuinely improve coverage, lock the win in with

bun packages/cli/src/library/fidelity-floor.ts --raise --data packages/library-types/data

which raises each floor to the current coverage and can never lower one. A drop is therefore always a real regression to fix at the source, never a floor to edit down.

4. Check the API-doc description

After library check --api-doc-out, open api-doc/<namespace>.json and inspect info.description. It carries the description line on the library's main ---@class. When that class has no description line the value is empty (""), and the /api page renders with no description — the "every library page has a non-empty description" gate fails.

Remediate by adding a namespace-keyed entry to <data folder>/library-descriptions.json — "<namespace>": "<one-line summary>", keyed by namespace. The site's fallback in api-surface-loader.ts reads it for LuaLS libraries (a ts-defold library keys its fallback on the upstream classification dir; a LuaLS library has none, so it keys on the namespace directly). druid needs nothing here — its ---@class druid is described, so it never reaches the fallback. decore is the worked example: its ---@class carries no description, its api-doc/decore.json info.description is "", and the committed "decore": "Defold ECS Data Manager" entry supplies the page description.

5. Validate, then commit

Run library check over the library data. It runs the reader's checks, prints every module, and type-checks every module resolve prints under skipLibCheck: false, together with each library folder's usage/ examples, so a new target is compiled as soon as its recipe.json lists it; the dts-declaration-validity test runs the same check. Fidelity parity is gated per namespace. Then run the library tests:

bunx @defold-typescript/cli library check --data packages/library-types/data  # from the toolchain root
bun test packages/cli/src/library  # from the toolchain root
bun run typecheck  # from the toolchain root
bun packages/cli/src/library/fidelity-floor.ts --raise --data packages/library-types/data  # from the toolchain root

A brand-new library has no floor entry yet, and the floor gate fails until it gets one — fidelity-floor.ts --raise seeds it at the coverage you just measured.

Commit the library's library.json with its floor, reviewed.json and recipe.json and the snapshotted source/<namespace>/ together. Both emitted report folders (fidelity/, api-doc/) are gitignored here and stay uncommitted.

Worked example — druid

The druid entry is the reference shape:

{
  "repo": "https://github.com/Insality/druid",
  "ref": "1.2.5",
  "license": "MIT",
  "sourceGlobs": ["druid/**/*.lua"],
  "moduleId": "druid.druid",
  "namespace": "druid",
  "typeRenames": {
    "vector": "Vector",
    "vector3": "Vector3",
    "vector4": "Vector4"
  },
  "ignore": ["**/test/**", "**/example/**", "**/example_*/**"],
  "externalTypes": { "event": { "module": "event.event", "name": "event" } }
}

sourceGlobs snapshots the whole druid/ tree; ignore drops its tests and examples; moduleId druid.druid scopes the exported functions to druid/druid.lua while the interfaces merge from every file; typeRenames maps druid's vmath references onto the toolchain's branded Vector* types; externalTypes hands druid's callback fields to the event library that owns them. From these fixtures, or from the druid archive a project depends on, resolve prints the declaration it materializes into a consuming project as druid.druid.

Libraries that ship a .script_api

A native or hybrid library that ships an extension .script_api (the same YAML format every Defold extension ships) has a third ingestion mode, distinct from the LuaLS front-end above: packages/cli/src/library/sync-script-api-types.ts, driven by the scriptApi list of a library's recipe.json. Instead of parsing ---@ annotations, it routes the committed .script_api snapshot through the shared ref-doc emitter — scriptApiToFixtureJson → generateModuleDeclaration, the exact path resolve-time extension typing uses — so one-level nested sub-namespaces (bridge.platform, bridge.achievements) survive into nested namespace blocks. The output is an importable module keyed by moduleId (declare module 'bridge.bridge'), matching the LuaLS library goldens, so the library imports under its pinned specifier; the declare global form stays the resolve emitter's, for extensions a project declares.

Each entry names scriptApi (the path to the .script_api in the repo), moduleId, namespace, and the exact apiDoc / fidelity output paths; the library folder pins repo and ref as above. The generate arms mirror the LuaLS ones:

# snapshot the pinned .script_api into <library>/source/<moduleId>.script_api
bun packages/cli/src/library/sync-script-api-types.ts --fetch --data packages/library-types/data
# build the pinned fidelity/<...>.json
bun packages/cli/src/library/sync-script-api-types.ts --fidelity --data packages/library-types/data
# check library data, then lower the pinned api-doc/<...>.json (raw ref-doc doc, uniform with the engine fixtures)
bun packages/cli/src/bin.ts library check --data packages/library-types/data --api-doc-out packages/library-types/api-doc

The first migrated target is Playgama/bridge-defold (pinned v2.3.0), maintained entirely from its .script_api — its former ts-defold binding is gone. Three things are specific to a script_api target and worth knowing:

  • Output paths are pinned explicitly and named for the single-segment namespace. Like the LuaLS libraries, a migrated script_api library is the sole maintainer of its namespace, so its goldens are api-doc/bridge.json and fidelity/bridge.json — not the dotted moduleId — which keeps the docs Libraries tree and the file layout uniform with druid. The require specifier is still the moduleId (declare module 'bridge.bridge'), so resolve prints it under that specifier.
  • Fidelity mirrors the emitter, so an unmapped token counts against coverage. The report is computed over the ref-doc doc with the emitter's own type map: a token the emitter renders as unknown is counted in unknownFallbacks and listed in unknownTokens rather than hidden. A pipe-separated type: or a YAML list (type: [table, string]) is split into one token per alternative before that check, so bridge's string | nil returns resolve to string | undefined and bridge lands at coverage 1. A slot left with no token at all counts as one unknown fallback, listed as (untyped), so it cannot pass as covered.
  • A parameter upstream calls omittable in prose only is declared, not inferred. The .script_api format cannot say that a middle parameter may be left out with the later ones shifting left, and upstream sometimes describes a trailing parameter as optional without marking it optional: true. A target lists either kind of slot under omittableSlots (element, slot, and the upstream evidence that allows it), and the emitted declaration carries two overloads, with and without it. The api-doc page and the fidelity report stay as upstream wrote them. A slot the fixture no longer has fails the emit, so the entry cannot go stale.

On this page