# defold-typescript

> Human-facing guide for the defold-typescript toolchain.

## Guide

### defold-typescript

Build your [Defold](https://defold.com/) game in [TypeScript](https://www.typescriptlang.org/) and get VSCode's full editor experience — autocomplete, inline type errors, and safe refactors — across the whole Defold API, while still shipping the plain [Lua](https://www.lua.org/) the engine runs.

- **The full Defold API, typed** — every module and namespace is typed from the official reference, so `go`, `gui`, `vmath`, `msg`, and the rest autocomplete and type-check as you write.
- **Compiles to plain Lua** — your TypeScript runs through the battle-tested [TypeScriptToLua](https://typescripttolua.github.io/) (TSTL) compiler down to the Lua Defold already runs: no engine fork, no proprietary runtime, no lock-in.
- **Typed scripts end to end** — `self`, `on_message`, and `on_input` payloads are typed through `defineScript`, `defineGuiScript`, and `defineRenderScript`.
- **Fits new and existing projects** — scaffold from scratch, or add the TypeScript surface to a project that already has `game.project` and adopt type safety gradually, one script at a time alongside your existing Lua.
  - **Preserves your project layout** — TypeScript blends into the existing project structure without creating a wrapper folder.
- **Built for the real loop** — `watch` recompiles beside the Defold editor, live transpile diagnostics surface errors inline, and source maps let you set breakpoints in your `.ts`.

This guide shows how to scaffold a project, write TypeScript that the toolchain compiles to Lua, and look up the language-and-toolchain quirks you will hit along the way.

The sections below mirror the top navigation; each lists the pages in its left-sidebar order. The repository `README.md` is generated from this file so the GitHub landing page and docs homepage stay aligned.

#### Get started

- [Getting started](./getting-started.md) — install Bun, scaffold a new project with `bunx @defold-typescript/cli@latest init my-game`, add TypeScript to an existing Defold project with `init .`, write a one-screen script, and build to Lua with `bunx @defold-typescript/cli build`.
- [Editor setup](./editor-setup.md) — open the project in VSCode, use the generated `tsconfig.json`, and run `bunx @defold-typescript/cli watch` beside the Defold editor.
- [Defold editor](./defold-editor.md) — install Defold, open the generated project folder, attach a compiled script (`.ts.script`, `.ts.gui_script`, or `.ts.render_script`) to its game object, GUI scene, or render pipeline, and run the game (TypeScript is transpiled to Lua by the CLI, not the editor).

#### Guides

##### Tutorial

- [Build Tetris](./tetris-tutorial.md) — build a complete Tetris game from scratch: write TypeScript, compile it to Lua, and wire the scene in the Defold editor, seeing the whole workflow end to end.

##### TypeScript

- [TypeScript vs Lua](./typescript-vs-lua.md) — the Lua-developer on-ramp: a cheat sheet that translates syntax, tables, modules, and the standard library from Lua to the TypeScript the toolchain expects.
- [TypeScript gotchas](./typescript-gotchas.md) — the canonical catalog of TS / [TypeScriptToLua](https://typescripttolua.github.io/) (TSTL) / Defold sharp edges. Today: the unary-minus quirk that silently produces `number` from a `Vector3`. Future entries land here as the toolchain encounters them.
- [Data structures](./data-structures.md) — what's built in for Defold: `Array`, tuple, `Map`, `Set`, `WeakMap`, `WeakSet`, object record, and `class`, each with its Lua lowering and `lualib` cost, plus the not-available list (regex, `BigInt`, `LinkedList`) and what to reach for instead.

##### Core concepts

- [Script lifecycle](./script-lifecycle.md) — type `self`, `on_message`, and `on_input` payloads with `defineScript`, `defineGuiScript`, and `defineRenderScript`.
- [Messages](./messages.md) — the `BuiltinMessages` catalog, `msg.post` send-side payload narrowing, and the `isMessage` / `onMessage` receive-side helpers.
- [Where script state lives](./script-state.md) — the four state tiers — per-instance `self`, a shared module local, a cross-script module singleton, and VM-global `declare global` — each grounded in the emitted Lua.
- [Vector math](./vector-math.md) — the method-form arithmetic surface (`add`, `sub`, `mul`, `div`, `unm`) on `Vector3`, `Vector4`, `Quaternion`, and `Matrix4`, plus why you cannot write `v3 + v3`.

##### CLI

- [init](./init.md) — scaffold a new Defold project with a TypeScript surface, or add TypeScript to an existing project; the two modes, the `--template` / `--force` flags, and the starter templates.
- [watch](./watch.md) — the incremental rebuild loop: recompile Lua on every save beside the Defold editor, and re-resolve the extension surface on `game.project` changes.
- [build](./build.md) — one-shot transpile of every `src/` TypeScript file to Lua, plus the headless `defold` subcommand that drives `bob` to build and bundle the project.
- [wall](./wall.md) — opt-in per-directory API walls that narrow a single-kind source directory to its script-kind surface, in interactive and flag forms.
- [resolve](./resolve.md) — generate ambient TypeScript namespaces from your `game.project` native-extension dependencies, with pin/drift detection and a `--frozen` lockfile mode.

##### Toolchain & workflow

- [Transpile diagnostics](./transpile-diagnostics.md) — the scaffolded `@defold-typescript/tstl-plugin` language-service plugin that surfaces TypeScript-to-Lua transpile errors live in the editor, advisory-only and never blocking `tsc --noEmit`.
- [Debugging](./debugging.md) — step through `.ts` source with breakpoints via the Local Lua Debugger and the scaffolded Bun launch path (no shell, Windows-native), resolving through the emitted `<name>.ts.script.map`.
- [Agent runbooks](./agent-runbooks.md) — harness-neutral procedures for driving the CLI from an automated agent: scaffold a project, [install the agent contract](./agent-runbooks.md#install-the-agent-contract), regenerate extension types, [add and attach a script](./agent-runbooks.md#add-a-script) (build, wire the compiled component, verify), and fix the Lua output over the `--json` envelope, gating on `ok`.
- [Helper scripts](./helper-scripts.md) — where build, codegen, and maintenance scripts live: a project-root `/scripts` folder run with Bun, typed by their own `scripts/tsconfig.json`, kept off the Lua build path and out of the Defold-typed `src/` surface.

##### Project configuration

- [Pinning the Defold version](./pinning-defold-version.md) — keep the default latest surface, or pin an older Defold version whose API surface is generated on the fly and materialized into a project-local `.defold-types/<version>/`.
- [Native extensions](./extensions.md) — declare an extension in `game.project` `[dependencies]`, then run [`resolve`](./resolve.md) to generate an ambient namespace per `.script_api` into a gitignored `.defold-types/extensions/` surface, and consume it with no import.

##### Migration

- [API docs vs `ts-defold-types`](./api-docs-vs-ts-defold.md) — a factual, dimension-by-dimension comparison of the JSDoc that `@defold-typescript/types` and `ts-defold-types` emit (Markdown conversion, dash params, grid-aligned multi-line docs, branded constants, the `@example` trade-off), with a picker for which surface fits your project.
- [Migrating from `ts-defold`](./migrating-from-ts-defold.md) — move a project off the `@ts-defold/*` stack: the package/tooling map, the step-by-step port via `init` add-TypeScript mode and a `tsconfig.json` reconcile, and the type-surface differences you will hit.

#### Reference

- [API](/api) — the generated `@defold-typescript/types` reference: every documented Defold namespace, grouped alphabetically as cards (site-only; built from the typed surface the toolchain ships).
- [Lua standard library](/api/base) — the pure-Lua / LuaJIT reference category (`base`, `bit`, …). Types are owned by the `lua-types` dependency the `lua-stdlib-globals` goal adopted; `@defold-typescript/types` does not re-emit them as generated namespaces.
- **For AI agents** — machine-readable docs per [llmstxt.org](https://llmstxt.org/):
    * [`llms.txt`](https://defold-typescript.github.io/toolchain/llms.txt) is the map (start here)
    * [`llms-full.txt`](https://defold-typescript.github.io/toolchain/llms-full.txt) is the full corpus (grep it, never read it whole). The same pair ships into a consumer's `node_modules/@defold-typescript/docs/` on install.

### Getting started

Scaffold a Defold project with TypeScript sources, write a script, and build to Lua. The whole loop runs on Bun — no `npm` or `node`.

Coming from Lua? See [TypeScript vs Lua](./typescript-vs-lua.md) for a translation cheat-sheet.

Coming from ts-defold? See [Migrating from ts-defold](./migrating-from-ts-defold.md).

#### Install Bun

Follow the official instructions at [bun.sh](https://bun.sh/). Verify:

```sh
bun --version
```

You need Bun `>= 1.3`.

#### Scaffold a project

The package is scoped, so run it through `bunx` by its full name — no install required:

```sh
bunx @defold-typescript/cli@latest init my-game
cd my-game
git init
bun install
```

> `my-game` will be created if it doesn't exist.
>
> **Optional**: Run `bunx @defold-typescript/cli@latest init-agents .` to initialize `AGENTS.md` and `CLAUDE.md` files.

```sh
bunx @defold-typescript/cli@latest init .
git init
bun install
```

> `.` scaffolds into the folder you are already in.

`init` writes a minimal Defold project (`game.project`, `main/main.collection`, `input/game.input_binding`) alongside a TypeScript surface (`src/main.ts`, `tsconfig.json`, `package.json`). `game.project` boots the collection from its `[bootstrap]` section and points `[input]` at the binding, so a fresh scaffold loads in Defold with no missing references. The collection points at the generated `src/main.ts.script`, so the TypeScript starter is the script Defold runs.

See [Init](./init.md) for more options.

> [!NOTE] `init` requires an explicit destination — there is no implicit "current folder" default, so it never scaffolds where you did not mean to. Pass a path to create (or add to) that folder, or `.` to target the folder you are already in.

> [!TIP] `init` also generates a `mise.toml`. If you already have [mise](https://mise.jdx.dev) installed, it flags the new file as untrusted — run `mise trust` once to approve it.
> After that, `mise run` (or its shorthand `mise r`) lets you pick one of the scaffolded tasks interactively.

Use the `@latest` tag when you scaffold: `bunx` caches binaries, and `init` is
what writes your `@defold-typescript/types` version pin, so a stale cache would
pin an older release. `@latest` always scaffolds against the current version.

Check which version you are running with `-v` / `--version`:

```sh
bunx @defold-typescript/cli --version
```

#### Add TypeScript to an existing project

`init` is not just for fresh directories. Run it inside an existing Defold project to drop in the TypeScript infrastructure (`package.json`, `tsconfig.json`, `.gitignore`, `biome.json`, editor settings, and managed tasks) without touching `.script`, `.collection`, `.gui_script`, `.render_script`, `game.project`, or other engine assets.

1. `cd` into the project, such as a clone of [`defold/template-platformer`](https://github.com/defold/template-platformer).
2. Run `bunx @defold-typescript/cli@latest init .` (the `.` targets the current folder).
3. Run `bun install`, matching the install reminder printed by `init`.
4. Hand-convert your Lua scripts to TypeScript — move each Defold lifecycle hook into a `defineScript({...})` method; the [platformer example](https://github.com/defold-typescript/toolchain/tree/main/docs/examples/platformer) is a worked conversion.
5. Run `bunx @defold-typescript/cli build` to transpile the converted sources.
6. Open the project in the Defold editor and Build-and-Run.

#### Update `@defold-typescript` version

To update to the latest version:

```sh
bunx @defold-typescript/cli@latest init . --force
```

Despite the intimidating name, `--force` does not overwrite your source files — `src/main.ts`, `.script`, `.collection`, `game.project`, and other engine assets are left alone. It only refreshes the managed config (`tsconfig.json`, `biome.json`, and the `@defold-typescript` dependency pins), so an existing project keeps up with the current toolchain.

#### Project structure

`@defold-typescript` doesn't create any folder wrappers around your Defold project, and instead adds TypeScript infrastructure in-place.

The scaffold declares its `devDependencies` in `package.json`:
* `@defold-typescript/types` for the editor's ambient Defold types
* `@defold-typescript/cli` pinned to the same version so the build runs in
lockstep with those types
* `@defold-typescript/tstl-plugin` for the live transpile diagnostics
* `@biomejs/biome` for lint and format
* `@types/bun` for the `.vscode/` debug launcher
* `lua-types` for the ambient Lua standard library so `math`/`string`/`table`/… resolve

`bun install` is what actually downloads these dependencies to the `node_modules` folder (it is gitignored inside the generated `.gitignore`).
If you forget to do so, your editor reports the Defold globals as unresolved.

> [!WARNING] If you are using VSCode, you may need to open the `main.ts` file and run `Restart TS Server` from the Command Palette, or simply reload the window if the errors persist even after installing all the dependencies.

> [!TIP] `init` does not install for you (that keeps scaffolding offline), so
> it prints a `Next: run <pm> install` reminder once it finishes, picking the
> package manager from the runner that invoked it (`bun`/`npm`/`pnpm`/`yarn`,
> falling back to `bun`).
>
> Pass `--suppress-install-reminder` to silence that line when you install through your own tooling.

The scaffold also ships an opinionated `biome.json`, so the project lints and formats cleanly out of the box. An existing `biome.json` is left untouched, unless you pass `--force`, which migrates the one deprecated Biome `recommended` key and leaves your other settings in place.

If the scaffolded `@defold-typescript/types` pin still looks older than the CLI you expect, your `bunx` cache is stale — `@latest` above already forces the current release, which is more reliable than clearing the cache with `bun pm cache rm`.

#### Write a script

By default, only `.ts` files under the project's `src/` folder are compiled. That scope is the `include` array in `tsconfig.json` (both `build` and `watch` honor it) — widen it to manage more folders:

```json
{
  "include": ["src/**/*.ts"]
}
```

Open `src/main.ts` and replace its body with:

```ts
import { defineScript } from "@defold-typescript/types";

export default defineScript({
  properties: {
    name: hash("player"),
  },
  init(self) {
    // self is the property channel here, not the merged self the other hooks see.
    const start = vmath.vector3(0, 0, 0);
    const offset = vmath.vector3(1, 1, 0);
    const target = start.add(offset);
    print(`target: ${target.x}, ${target.y}, ${target.z}`);
    return { target };
  },
});
```

`defineScript` is the one import — it wires `init` (and the other lifecycle hooks) to Defold's script table. `vmath`, `print`, and the `Vector3` shape are ambient globals, so they need no import.

> [!NOTE]
> Inside `init`, `self` is the property channel. In every other hook, `self` widens to the union of the property channel and whatever `init` returns.

#### Build to Lua

```sh
# one-time build
bunx @defold-typescript/cli build
# rebuild on every change while you edit
bunx @defold-typescript/cli watch
```

[`build`](./build.md) transpiles every TypeScript file under `src/` to Lua and writes the result into the Defold project tree — each source becomes exactly one output: a lifecycle-factory file becomes a Defold script component (`src/main.ts` -> `src/main.ts.script`), a plain module becomes a Lua module (`src/util.ts` -> `src/util.lua`). Open the project in the [Defold editor](./defold-editor.md) to play it, or build and run it headlessly — see [Build](./build.md) for the full behavior, the generated-file markers, and the headless `defold` subcommand.

While you edit, run [`watch`](./watch.md) instead: it rebuilds incrementally on every save and keeps the native-extension surface current (run [`resolve`](./resolve.md) once first). See [code editor setup](./editor-setup.md) for the VSCode and integrated-terminal loop.

### Code editor setup

Open the Defold project folder in VSCode or any editor with TypeScript support. Use the folder that contains `game.project`, `src/`, and `tsconfig.json`.

#### What `tsconfig.json` provides

The generated `tsconfig.json` sets:

- `types: ["@defold-typescript/types"]` so Defold globals such as `vmath`, `msg`, and `print` type-check in `src/*.ts`.
- no `outDir`, so generated Lua lands next to its `.ts` source. Lifecycle-factory files become Defold components (`src/main.ts` -> `src/main.ts.script`), while helper-only imports become Lua modules (`src/util.ts` -> `src/util.lua`). Set a concrete `outDir` to collect the outputs under a separate tree instead.
- `strict: true` so project code gets normal TypeScript checks.

VSCode's built-in TypeScript support reads this file automatically when the project folder is open.

#### Hover documentation

The generated type declarations carry the Defold reference docs inline as JSDoc. Hovering a Defold symbol in `src/*.ts` shows its description straight from the engine API docs — functions also list each parameter (`@param`) and their return (`@returns`), plus a worked `@example` code block when the engine docs ship one; constants, variables, and component `properties` show a summary line. The core consumer-facing modules (`vmath`, `go`, `msg`, `sprite`) render their `@example` blocks as idiomatic TypeScript — see [TypeScript vs Lua](typescript-vs-lua.md) for the idiom mapping — while the remaining modules fall back to the engine's Lua sample until translated. No extra extension required, since it rides on VSCode's built-in TypeScript support. Autocomplete surfaces the same text. Undocumented engine symbols simply show their signature with no description.

Hover docs reach beyond the generated signatures: the overloaded facades (`msg.post`, `go.get`/`go.set`) and the hand-authored helpers (`isMessage`, `onMessage`) carry the same summary + `@param` + `@returns` + `@example` blocks, so the receive-side message helpers hover as richly as the generated namespace API.

#### Recommended editor extensions

You edit TypeScript, not Lua, and the build runs from the CLI — so the required extension stack is minimal:

- TypeScript support: built into VSCode. This is what type-checks `src/*.ts` against `@defold-typescript/types`; no extra extension needed.
- [Local Lua Debugger](https://marketplace.visualstudio.com/items?itemName=tomblind.local-lua-debugger-vscode) (`tomblind.local-lua-debugger-vscode`) — **required for debugging**: steps through your `.ts` source via the emitted source maps. See [Debugging](debugging.md) for the launch path.

> [!WARNING]
> **Defold Kit (`astronachos.defold`) is not needed.** This toolchain ships its own ambient Defold types and a CLI build loop, so the Kit's annotation sync is redundant — and its setup wizard overwrites files this toolchain manages. `init` no longer recommends it.

Defold runs standard Lua 5.1 (LuaJIT), **not** Luau. If you want to read the *generated* Lua, [sumneko Lua](https://marketplace.visualstudio.com/items?itemName=sumneko.lua) (`sumneko.lua`) adds a Lua language server — optional, and no longer auto-recommended, since you author in TypeScript.

> [!WARNING]
> Avoid the Roblox **Luau Language Server** (`johnnymorganz.luau-lsp`) in a Defold project: it reports `Failed to load sourcemap.json` and bogus diagnostics, because it expects a Roblox/Rojo `sourcemap.json` — an artifact this toolchain never produces. The `*.ts.script.map` files next to your output are [TypeScriptToLua](https://typescripttolua.github.io/) (TSTL) source maps, unrelated to Roblox's `sourcemap.json`.

`init` scaffolds a `.vscode/` folder that encodes this:

- `extensions.json` recommends only Local Lua Debugger and marks the Luau LSP as unwanted.
- `settings.json` sets `Lua.workspace.ignoreDir: ["src"]` so that, *if* you install the optional sumneko Lua server, it does not lint the generated `*.ts.script` output (which would flag TSTL-emitted `self` parameters as unused). Hand-written Defold `.script` files under `main/` stay analyzed. The setting is harmless when sumneko is absent.
- `defold-typescript.code-snippets` expands an empty script over the lifecycle factories (the TypeScript equivalent of the Defold editor's "new script" templates).
- `launch.json` + `defold-debug.ts` set up a shell-free, Windows-native debug launch path. See [Debugging](debugging.md).
- `tasks.json` registers `defold-typescript: build` / `defold-typescript: watch` tasks with a shared problem matcher, so transpile errors land in the editor's Problems panel.

These files merge additively into any `.vscode/` config you already have, so your own recommendations, settings, snippets, and launch configs are preserved.

#### Script snippets

In any `.ts` file, type one of these prefixes and accept the completion to scaffold a whole empty script over `defineScript` / `defineGuiScript` / `defineRenderScript`:

| Prefix                                    | Scaffolds                                 |
| ----------------------------------------- | ----------------------------------------- |
| `def-ts-defineScript-inferred-self`       | script, state inferred from `init`        |
| `def-ts-defineScript-typed-self`          | script, explicit `Self` type              |
| `def-ts-defineGuiScript-inferred-self`    | GUI script, state inferred from `init`    |
| `def-ts-defineGuiScript-typed-self`       | GUI script, explicit `Self` type          |
| `def-ts-defineRenderScript-inferred-self` | render script, state inferred from `init` |
| `def-ts-defineRenderScript-typed-self`    | render script, explicit `Self` type       |

The two variants mirror the two self-typing idioms (see [Script lifecycle](script-lifecycle.md)). The inferred variant returns an inline object from `init`, and `TSelf` follows that return — the documented default. The typed variant declares a named `Self` type and passes it explicitly as `defineScript<Self>(…)`, the escape hatch for when you want to name the state shape up front. Render snippets omit `on_input`, which `RenderScriptHooks` does not expose.

##### Keeping snippets and types in sync

An expanded snippet emits every lifecycle hook the installed `@defold-typescript/types` declares. If your editor reports `<hook> does not exist in type 'ScriptHooks'` (and the parameters of that method turn implicitly `any`), work through it in this order:

1. **Restart the TypeScript server first.** A stale language-server process keeps the old type surface in memory after a dependency upgrade, so the error survives even once the right types are on disk. In VS Code, run *TypeScript: Restart TS Server* from the command palette. This clears most false positives.
2. **Then bring the types up to the CLI.** The snippet emits whatever the *CLI* knows about, so a newer hook (such as `fixed_update` or `late_update`) errors when the project's resolved `@defold-typescript/types` lags the CLI that wrote the snippet. Upgrade to the latest and keep them in lockstep: `bunx @defold-typescript/cli@latest init . --force` repins the managed `@defold-typescript/types` dependency to the CLI's own version.

Edit TypeScript under `src/`. Treat generated `.ts.script`/`.ts.gui_script`/`.ts.render_script` component files, helper `.lua` modules, and their `.map` siblings next to your sources as build output; the scaffolded `.gitignore` keeps them out of version control.

#### Run the watch loop

Keep Defold open on the same project folder, and in the editor's integrated terminal run [`watch`](./watch.md):

```sh
bunx @defold-typescript/cli watch
```

It rebuilds Lua when files under `src/` change; run the game from the Defold editor after each rebuild. See [Watch](./watch.md) for the incremental-session behavior, the extension-surface reconciliation, and the `mise` task equivalent (also listed below).

#### Opinionated `mise.toml`

`init` scaffolds (or additively merges into) an opinionated `mise.toml` with the following tasks. The block is marker-fronted, so re-running `init` refreshes the managed tasks without disturbing your own `[tools]` or `[tasks.*]` entries.

- **`defold-typescript:build`** — `bunx @defold-typescript/cli build`. Builds once with the project's CLI.
- **`defold-typescript:watch`** — `bunx @defold-typescript/cli watch`. The watch loop above, as a task.
- **`defold-typescript:resolve`** — `bunx @defold-typescript/cli resolve`. Materializes the native-extension and vendored-library type surfaces from `game.project` dependencies. `watch` runs this automatically on every `game.project` change, so it is mainly a one-off after adding a dependency.
- **`defold-typescript:setup-debug`** — `bunx @defold-typescript/cli setup-debug`. Wires the lldebugger `game.project` dependency and entry-script bootstrap (see [Debugging](debugging.md)).
- **`defold-typescript:init-agents`** — `bunx @defold-typescript/cli init-agents .`. Materialize or refresh the `AGENTS.md` / `CLAUDE.md` AI-harness contract.
- **`defold-typescript:upgrade`** — `bunx @defold-typescript/cli@latest init . --force --suppress-install-reminder` then `bun install` (the second command reinstalls, so the install reminder is suppressed). The deliberate upgrade path.

Build and watch carry no version tag, so inside an installed project `bunx` resolves the `@defold-typescript/cli` that `init` scaffolds as a pinned devDependency — the build runs the version locked alongside the pinned `@defold-typescript/types`. Upgrade is the one task that intentionally pulls `@latest`: `init . --force` re-pins both managed deps to the new CLI's version, and `bun install` reinstalls.

> **Upgrading from a pre-`init .` project.** `init` now requires an explicit destination, but a `mise.toml` scaffolded by an older CLI carries a `:upgrade` task that calls `init --force` with no path. The first `mise run defold-typescript:upgrade` therefore fails with `a destination folder is required`. Run `bunx @defold-typescript/cli@latest init . --force` once by hand: it rewrites the managed `mise.toml` blocks (the refresh runs on every `init`, not just `--force`) so the dotted `:upgrade` task lands on disk and the task works from then on.

### Defold editor

Install the Defold editor from [defold.com](https://defold.com/). The editor is the engine UI you use to open the project folder, inspect assets, and run the game.

In the CLI-driven loop you author code in TypeScript and build from the command line (`defold build`, see [Build](build.md#headless-builds-no-editor)) — so the editor is opened mainly for **visual assets**: collections, atlases, tilemaps, GUI scenes, and previewing the running game. Compiling and running can happen entirely from the CLI without it.

#### Open the project

1. Start Defold to open the launcher. (If the editor is already open, choose **File** → **Open Project** to bring the launcher back up.)
2. On the launcher, click **Open From Disk...** and select the `game.project` file in your project folder.

For a project created with `bunx @defold-typescript/cli@latest init my-game`, that is the destination folder you named — the same folder where you run the CLI commands.

#### Build before running

Run the TypeScript build before launching the game:

```sh
bunx @defold-typescript/cli build
# or keep it running while you edit:
bunx @defold-typescript/cli watch
```

By default the scaffolded `tsconfig.json` has no `outDir`, so generated Lua lands next to its `.ts` source.

Lifecycle-factory files — those whose `export default` is one of these factories — become Defold script components, ready to be attached.

| Source factory       | Compiled artifact         | Referenced by                                                  |
| -------------------- | ------------------------- | -------------------------------------------------------------- |
| `defineScript`       | `<name>.ts.script`        | a game object (`.go` / `.collection`) as a component           |
| `defineGuiScript`    | `<name>.ts.gui_script`    | a GUI scene (`.gui`), as its **Script** property               |
| `defineRenderScript` | `<name>.ts.render_script` | the render pipeline (a `.render` file, set via `game.project`) |

A source exporting no lifecycle factory compiles to a Lua module (`src/util.ts` -> `src/util.lua`) — a generated artifact you import through the `.ts` and never edit or reference by hand. Keep generated output up to date with `build` or `watch` while you work.

Set a concrete `outDir` if you prefer the outputs collected under a separate tree.

#### Attach a script to a game object

A built script does nothing on its own. `src/main.ts` compiles to `src/main.ts.script`, but it runs only once it is added to a game object as a component — a new script that "does nothing" is almost always unattached, and its `properties` stay inert until it is a live component instance.

In the editor, select a game object (in a `.go` file or a collection), add the compiled `.ts.script` as a component, and Build. Defold writes the `component: "/src/….ts.script"` reference for you; you always point at the compiled `.ts.script`, never the `.ts` source. GUI and render scripts attach the same way — through a `.gui` scene's **Script** field and the render pipeline; see [Script lifecycle](./script-lifecycle.md#api-availability-by-script-kind) for which factory produces which kind.

Driving this without the editor — editing `.go` / `.collection` text directly and verifying the attachment from the command line — is the agent path: [Add a script](./agent-runbooks.md#add-a-script).

#### Run the game

With the project open in Defold, press **Build** or **Project > Build** to run the game. If you change TypeScript code, rebuild with `bunx @defold-typescript/cli build` before running again, or keep `watch` running in a terminal.

### TypeScript vs Lua

A translation cheat sheet for Defold developers who already know Lua. Lua on the
left, the TypeScript you write on the right. It is a map, not a tutorial: skim
the tables, port your mental model, and reach for the linked pages when a detail
bites.

For the runtime traps the type system cannot catch — `0` and `""` being truthy,
`nil` collapsing `null` and `undefined`, `typeof` not narrowing engine handles —
see [TypeScript gotchas](./typescript-gotchas.md). This page only flags those at
cheat-sheet depth and links down.

#### Syntax at a glance

| Concept                | Lua                      | TypeScript                                                                                                                                                            |
| ---------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Line comment           | `-- note`                | `// note`                                                                                                                                                             |
| Block comment          | `--[[ … ]]`              | `/* … */`                                                                                                                                                             |
| Bind a local           | `local x = 1`            | `const x = 1` (never reassigned), `let x = 1` (reassigned)                                                                                                            |
| Not equal              | `a ~= b`                 | `a != b` or `a !== b` — identical Lua (see the [gotchas page](./typescript-gotchas.md#-and--compile-to-the-same-lua--strictness-is-a-convention-not-a-runtime-guard)) |
| Equal                  | `a == b`                 | `a == b` or `a === b` — identical Lua (see the [gotchas page](./typescript-gotchas.md#-and--compile-to-the-same-lua--strictness-is-a-convention-not-a-runtime-guard)) |
| Logical and / or / not | `and` / `or` / `not`     | `&&` / `\|\|` / `!`                                                                                                                                                   |
| String join            | `"a" .. b`               | `"a" + b`, or a template literal `` `a${b}` ``                                                                                                                        |
| Length                 | `#t`                     | `t.length`                                                                                                                                                            |
| Block delimiters       | `then … end`, `do … end` | `{ … }`                                                                                                                                                               |
| Absence                | `nil`                    | `null` and `undefined` (both lower to `nil` — see the gotchas page)                                                                                                   |
| Index base             | 1-based: `t[1]`          | 0-based: `arr[0]`                                                                                                                                                     |

Two things to internalise before the rest of the page:

- **Equality has no loose/strict split here.** `==` / `!=` and `===` / `!==`
  compile to the *same* non-coercing Lua `==` / `~=`, so JavaScript's
  coercion — the thing `===` guards against — never happens in the output. The
  scaffolded `biome.json` ships `noDoubleEquals` off, so neither form lints; use
  whichever reads best — the worked examples here (such as the Tetris build) use
  `==` / `!=` to mirror Lua's `==` / `~=`. Both are value equality for primitives
  and reference equality for objects — the same split Lua draws between
  numbers/strings and tables. The one real equality trap is `if (cell)`
  truthiness, since `0` is truthy in Lua — see the [gotchas page](./typescript-gotchas.md#-and--compile-to-the-same-lua--strictness-is-a-convention-not-a-runtime-guard).
- **Indexing flips from 1 to 0.** This is the single biggest porting bug. A Lua
  `for i = 1, #t` loop becomes a `for (let i = 0; i < arr.length; i++)` loop, and
  every literal index shifts down by one. Prefer `for…of` (below) so you never
  touch the index at all.

#### Tables vs objects, arrays, and Maps

Lua has one container — the `table` — used for records, arrays, and dictionaries
alike. TypeScript splits that one type into three, each with its own syntax and
methods. Pick the one that matches how you actually use the data:

| Lua `table` used as…           | TypeScript                                                     | Notes                                                                                                                            |
| ------------------------------ | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Record / struct                | object literal `{ x: 1, y: 2 }`                                | fixed, named string keys                                                                                                         |
| Record with a computed key     | object literal `{ [graphics.BUFFER_TYPE_COLOR0_BIT]: params }` | bracketed key from an expression — Lua's `[expr] = v` (e.g. `render.render_target` option tables keyed by engine enum constants) |
| Sequence / list                | array `[1, 2, 3]`                                              | 0-based; `arr.length`, `arr.push(x)`                                                                                             |
| Dictionary with arbitrary keys | `Map`                                                          | `new Map()`, `.set(k, v)`, `.get(k)`; non-string keys                                                                            |

Iteration translates the same way:

| Lua                         | TypeScript                                       |
| --------------------------- | ------------------------------------------------ |
| `for _, v in ipairs(t) do`  | `for (const v of arr)`                           |
| `for k, v in pairs(t) do`   | `for (const [k, v] of Object.entries(obj))`      |
| `for k, v in pairs(map) do` | `for (const [k, v] of map)` (or `map.entries()`) |

Do **not** use `for…in` to walk an array — TypeScriptToLua rejects it because
JavaScript `for…in` iterates keys in an unspecified order that differs from Lua.
Use `for…of` for values, `Object.entries` / `Map.entries` for pairs.

Under the hood TypeScriptToLua still stores arrays in 1-based Lua tables; you
write 0-based TypeScript and the transpiler emits the offset. The one place the
abstraction leaks is sparse arrays: setting an element to `null`/`undefined` or
leaving holes can make `arr.length` and Lua's `#` disagree, so keep arrays dense.

Beyond these three, TypeScript also gives you `Set`, `WeakMap`, `WeakSet`, and
`class`, and rejects a few things outright (regex, `BigInt`). For the full map of
what is built in, what each lowers to, its `lualib` cost, and what to reach for
when something is missing, see [Data structures](./data-structures.md).

#### Modules: `require` vs `import`

Lua wires files together with `require` and a returned table. TypeScript uses
`import` / `export`, and TypeScriptToLua lowers them straight back onto Lua's
module system — an `import` becomes a `require`, and your `export`s become the
module's returned table.

| Lua                                        | TypeScript                                     |
| ------------------------------------------ | ---------------------------------------------- |
| `local M = {}` … `return M`                | `export function f() {}`, `export const C = …` |
| `local foo = require("foo")`               | `import { f, C } from "./foo"`                 |
| `local foo = require("foo")` (whole table) | `import * as foo from "./foo"`                 |

Use **relative** specifiers (`"./foo"`, `"../lib/util"`) for your own files under
`src/`. Engine APIs are different: the namespaces `go`, `msg`, `vmath`, `sprite`,
`gui`, `render`, and the rest ship from `@defold-typescript/types` as **ambient
globals**, so you call `vmath.vector3(…)` or `msg.post(…)` with no import at all.
You only `import` your own modules.

#### File structure and script mapping

You edit TypeScript under `src/`; the toolchain emits Lua beside each source by default. Files that call lifecycle factories become Defold-loadable components, and helper-only files become Lua modules for imports:

```text
src/main.ts   →   src/main.ts.script
src/util.ts   →   src/util.lua
```

Defold resolves a resource by the extension after its last dot, so a `.ts.script` file is a valid `.script` component the engine loads directly — the `.ts` in the name only marks its TypeScript origin. `src/util.lua` is a plain Lua module whose path matches the `require("src.util")` emitted for `import "./util"`. Run `bunx @defold-typescript/cli build` once or `bunx @defold-typescript/cli watch` to keep outputs current.

Lua scripts attach behaviour by defining bare global callbacks (`function
init(self)`, `function on_input(self, action_id, action)`). In TypeScript you
type those through `defineScript` instead, which gives `self` and the message and
input payloads real types. See [script lifecycle](./script-lifecycle.md) for the
full surface and the per-kind API walls.

#### Standard library and built-ins

This is where Lua and TypeScript diverge most, because they ship different
standard libraries. TypeScriptToLua targets the **ECMAScript** feature set: when
you write idiomatic TypeScript — array methods, string methods, `Math`, template
literals — the transpiler emits the matching Lua via its runtime library. So the
idiomatic move is to use the TypeScript form, not to call the Lua global.

| Lua                            | Idiomatic TypeScript          |
| ------------------------------ | ----------------------------- |
| `table.insert(t, x)`           | `arr.push(x)`                 |
| `#t`                           | `arr.length`                  |
| `string.format("%d", n)`       | template literal `` `${n}` `` |
| `tostring(x)`                  | `` `${x}` `` or `String(x)`   |
| `tonumber(s)`                  | `Number(s)`                   |
| `string.sub`, `string.find`, … | `str.slice`, `str.indexOf`, … |
| `math.abs`, `math.floor`, …    | `Math.abs`, `Math.floor`, …   |

A caveat worth knowing: `Array.prototype.sort` lowers to Lua's `table.sort`,
which is **not stable**, unlike JavaScript's guaranteed-stable sort. If element
order among equal keys matters, sort on a tiebreaker.

The raw Lua standard library — the `math`, `os`, `string`, `table`, and
`coroutine` tables plus base globals like `pairs`, `ipairs`, `pcall`, `print`,
`tostring`, `type`, `assert`, and `setmetatable` — **is** part of the ambient
surface: `@defold-typescript/types` references the `lua-types` package, so these
type-check and autocomplete with no import. Defold's own `hash()` is ambient too
and returns `Hash`. Reach for a local `declare global` only for genuinely
Lua/Defold-specific globals the type package does not cover.

A `declare global` block is type-only: it **emits no Lua**. The first assignment
to the declared name is what creates the global at runtime, and it lowers to a
bare VM-wide Lua global — no `local`, no module prefix. Given
`declare global { var FOO: number }`, the use site `FOO = FOO + 1` compiles to
exactly `FOO = FOO + 1`. That global is shared across the entire VM, broader than
a `require`-cached module local, so for ordinary app state prefer a module
singleton — see [Where script state lives](./script-state.md) for the full
placement picture.

Two of Lua's basic types deserve a note because Defold leans on them. **Userdata**
is arbitrary C data stored in a Lua variable — Defold uses it for hashes, URLs, the
math objects (`vector3`, `vector4`, `matrix4`, `quaternion`), game objects, GUI
nodes, render predicates, render targets, and constant buffers. You never name
`userdata` in TypeScript: each one surfaces as a distinct branded type (`Hash`,
`Url`, `Vector3`, `Vector4`, `Matrix4`, `Quaternion`, …) so the compiler stops you
mixing a hash with a vector or a plain table. **Threads** are independent execution
contexts and back Lua coroutines; the ambient `coroutine` table (from `lua-types`)
creates and resumes them and returns a `LuaThread`. Coroutines work, but for
frame-paced waiting prefer Defold's own `timer.*` / `go.animate` scheduling.

Prefer the idiomatic-TypeScript column above wherever it exists. The case where
you must reach for the Lua global is **random numbers**. Defold's RNG is
deterministic until seeded, and the only way to seed it is the Lua call:

```ts
math.randomseed(os.time());
const roll = math.random(1, 6); // integer in [1, 6]
```

`Math.random()` and `math.random(m, n)` are not interchangeable. `Math.random()`
returns a `[0, 1)` float ([TypeScriptToLua](https://typescripttolua.github.io/) (TSTL)
lowers it to a Lua runtime helper) and cannot be seeded; `math.random(m, n)` returns
an integer in `[m, n]` from the seedable engine RNG. Use the Lua form whenever you
need a reproducible or integer-ranged result.

The transpiler targets **Lua 5.1** to match Defold's runtime (LuaJIT on native and
desktop, a 5.1 VM on HTML5). That keeps the emitted code clear of 5.4-only
constructs — integer division `//`, bitwise operators, `goto`, the two-argument
`math.randomseed` — which the engine would reject. The ambient `math.randomseed`
is correspondingly single-argument, so the two-argument form is a type error, not
a runtime surprise.

#### Libraries

- **Your own code** is just more TypeScript files — `import` them by relative
  path. No registration step, no manifest.
- **npm packages** work only if they transpile to self-contained Lua. A package
  that touches Node.js or browser built-ins (`fs`, `process`, `window`, `fetch`)
  will not run on the Defold Lua VM, because TypeScriptToLua implements the
  ECMAScript standard library and nothing host-specific.
- **Engine features** come from the ambient `@defold-typescript/types` namespaces
  (`go`, `msg`, `vmath`, …), never from npm. There is no package to install for
  them; they are part of the types surface the scaffold pins.

#### See also

- [TypeScript gotchas](./typescript-gotchas.md) — the runtime sharp edges this
  page only points at: truthiness, `nil` collapse, `typeof`, opaque handles.
- [Script lifecycle](./script-lifecycle.md) — typing `self`, `on_message`, and
  `on_input` with `defineScript`.
- [Where script state lives](./script-state.md) — per-instance `self`, shared
  module locals, module singletons, and the VM-global `declare global` lowering.
- [Data structures](./data-structures.md) — the full container availability map:
  `Array`, tuple, `Map`, `Set`, `WeakMap`, `WeakSet`, object record, and `class`,
  plus what is not available and what to use instead.
- [Vector math](./vector-math.md) — why `v3 + v3` is not allowed and you use
  `v3.add(other)` instead.
- [Getting started](./getting-started.md) — scaffold, write a script, build to
  Lua.

### TypeScript gotchas

Sharp edges where TypeScript, the TypeScriptToLua transpiler, or the Defold runtime behave in ways the type system cannot fully express. Each entry names the symptom, explains why it happens, and gives the recommended workaround.

New to TypeScript from Lua? Start with [TypeScript vs Lua](./typescript-vs-lua.md) for the syntax-and-idiom map; this page is the depth catalog you reach for when one of those quirks bites.

#### Before you start: Lua vs TypeScript gotchas

The one-line version of every trap on this page. Skim it once; jump to the full entry when one bites.

- [Unary minus on a vector yields `number`](#unary-minus-on-vector3--vector4-silently-produces-number) — `-v3` infers `number`, not `Vector3`; use `v.unm()`.
- [Enum constants are branded numbers](#enum-constants-are-branded-numbers--a-bare-number-wont-do) — a bare magic number won't satisfy an enum parameter; pass the named `go.PLAYBACK_*` constant.
- [Engine handles are opaque](#engine-handles-are-opaque--you-cannot-fabricate-or-cast-across-kinds) — a `node` is not a `texture`; obtain each handle from the API that returns it, never fabricate or cross-cast.
- [Callback parameters are `unknown`](#callback-parameters-type-check-as-functions-not-unknown) — match the documented arity; narrow each param before use.
- [Some slots are `unknown` on purpose](#some-slots-are-unknown-on-purpose--the-any-wildcard) — `socket.skip` and friends accept anything and force a narrow on the way out.
- [`if (x)` truthiness differs in Lua](#if-x-truthiness-differs--0-and--are-truthy-in-lua) — `0` and `""` are **truthy** once transpiled; test the value explicitly.
- [`typeof` cannot narrow engine values](#typeof-cannot-narrow-engine-values--they-are-lua-userdata) — Defold handles are Lua `userdata`, so `typeof x === "object"` is `false` for them at runtime.
- [`on_message` ids are hashes, not strings](#on_message-ids-are-hashes-not-strings) — compare `message_id` against a `hash("…")` constant; a string literal never matches at runtime.
- [`window.set_listener` hands `event` and `data` separately](#windowset_listener-hands-event-and-data-as-separate-params) — TS can't auto-narrow `data` from an `event` check; use the `isWindowEvent` guard.
- [`null`/`undefined`/`== null` all become `nil`](#null-undefined-and--null-all-collapse-to-nil) — the three TS forms collapse to one Lua check; you cannot tell them apart at runtime.
- [`===` and `==` are the same Lua](#-and--compile-to-the-same-lua--strictness-is-a-convention-not-a-runtime-guard) — both lower to a non-coercing Lua `==`; `==` is not JS loose equality here, and the real equality footgun is `if (cell)`.
- [`as` is not a runtime check](#as-is-a-compile-time-assertion-not-a-runtime-check) — a cast erases to nothing; the value is unverified at runtime.
- [Component properties are catalogued per namespace](#component-properties-are-catalogued-per-namespace) — read property types off `label.properties["color"]`, not off the namespace object.
- [`async`/`await` work but there is no event loop](#asyncawait-work-but-there-is-no-event-loop) — a `Promise` only advances when something resolves it synchronously; the importable `@defold-typescript/types/timers` polyfills bridge Defold's `timer.delay` so `await wait(s)` resumes on a later frame.
- [URL addressing: same-world is relative, `socket:` crosses worlds](#url-addressing-same-world-objects-are-relative-socket-crosses-worlds) — a sibling instance is `"camera"` or `"/camera"`, a sibling component is `"#name"`; `socket:` names a target world by its collection `Name` and is reserved for crossing into a collection-proxy-loaded world.

#### Unary minus on Vector3 / Vector4 silently produces `number`

**Symptom.** `-v3a` compiles cleanly and infers as `number`, not `Vector3`. Anything downstream that expects a `Vector3` (passing to `go.set_position`, chaining `.add(...)`, etc.) fails to compile with a confusing error pointing at the *use site*, not at the `-`.

```ts
declare const v3a: Vector3;

const neg = -v3a; // inferred as `number`, not `Vector3`
const target: Vector3 = -v3a; // TS error here — but the bug is the `-`
```

**Why.** TypeScript's TS2362 check ("operand of an arithmetic operation must be of type 'any', 'number', 'bigint' or an enum") applies to *binary* `+`, `-`, `*`, `/` but **not** to *unary* `-`. The unary form has its own narrow check that does not reject object-typed operands; it just produces `number`. There is no way to opt a type out of unary negation at the type-system level, so the `vector3` interface cannot defend itself.

**Typed alternative.** Use `v.unm()` — the same metamethod the Lua runtime would call for `-v`, but exposed as a typed method:

```ts
const neg: Vector3 = v3a.unm(); // returns Vector3
```

The same gap exists for `Vector4`; the same workaround applies: `v.unm()`.

**How we pin this in the type tests.** `packages/types/test-d/guide-snippets.ts` carries a symmetric proof: one line asserts `const _: number = -v3a` (which must compile), the next asserts `const _: Vector3 = -v3a` with `@ts-expect-error` (which must remain an error). If a future change either fixes the TS behavior or breaks the workaround, exactly one of the two lines flips and the typecheck gate fails.

#### Enum constants are branded numbers — a bare number won't do

**Symptom.** A call that the Lua runtime accepts with a magic number fails to typecheck when the parameter is an enum:

```ts
go.animate(id, "position.x", 2, 10, go.EASING_LINEAR, 1);  // TS error on `2`
go.animate(id, "position.x", go.PLAYBACK_ONCE_FORWARD, 10, go.EASING_LINEAR, 1);  // ok
```

**Why.** Defold's ref-doc encodes an enum member as a bare constant and lists the members' fully-qualified names as a parameter's accepted types. The generated typings recover each constant as a *nominally branded* number — `go.PLAYBACK_ONCE_FORWARD` has type `number & { readonly __brand: "go.PLAYBACK_ONCE_FORWARD" }` — and the parameter's type is the union of those brands. A plain `number` lacks the brand, so only a real `go.PLAYBACK_*` (or `go.EASING_*`) value satisfies it. This is intentional strictness: it stops you from passing the wrong magic number.

**Typed alternative.** Always pass the named constant (`go.PLAYBACK_ONCE_FORWARD`, `go.EASING_LINEAR`, …). The brand is type-only and erases at transpile time to a plain Lua global access, so there is no runtime cost. A branded constant is still assignable to any plain `number` parameter, so existing numeric signatures keep working.

**How we pin this in the type tests.** `packages/types/test-d/guide-snippets.ts` asserts the constant is assignable to `number` (backward compatibility) and to its own brand, while a bare `0` assigned to the brand carries `@ts-expect-error`. If the brand is dropped or widened, the expected error disappears and the typecheck gate fails.

**Constants can live in another namespace.** The brand is keyed on the constant's fully-qualified name, not on the namespace of the function that accepts it, so an enum can be owned by one namespace and consumed by another. The render buffer-type flags are the worked example: `render.get_render_target_width`, `render.get_render_target_height`, and `render.enable_texture` take a `graphics.BUFFER_TYPE_*` flag (`graphics.BUFFER_TYPE_COLOR0_BIT` … `_COLOR3_BIT`, `graphics.BUFFER_TYPE_DEPTH_BIT`, `graphics.BUFFER_TYPE_STENCIL_BIT`), and the named constant lives in the `graphics` namespace.

```ts
render.get_render_target_width(rt, graphics.BUFFER_TYPE_COLOR0_BIT);  // ok
render.get_render_target_width(rt, 0);                                // TS error on `0`
```

`packages/types/test-d/graphics-render-buffer-types.ts` pins this: the real `graphics` constant type-checks and a bare number carries `@ts-expect-error`.

#### Engine handles are opaque — you cannot fabricate or cast across kinds

**Symptom.** A GUI `node`, a render `texture` or `render_target`, a `buffer`, a `resource`, a box2d `b2World`/`b2Body`, and similar engine handles each have a distinct nominal type. A value obtained for one kind is not accepted where another kind is expected, and a plain value (a number, an object literal) is never accepted:

```ts
const n = gui.get_node("button");        // Opaque<"node">
render.enable_texture(0, n);             // TS error — a node is not a texture
render.set_render_target(undefined);     // TS error — undefined is not a render_target
```

**Why.** Defold's ref-doc names these handles by a bare token (`node`, `texture`, `buffer`, …) with no public structure. The generated typings recover each as `Opaque<"<token>">` — a phantom-branded type whose brand is the token string. Distinct tokens carry distinct brands, so they are mutually non-assignable, and because the brand is a `unique symbol` property no plain value satisfies it. This mirrors the `Hash`/`Url` brands: the strictness stops you from passing a handle of the wrong kind or conjuring one from thin air.

**Typed alternative.** Obtain the handle from the engine API that returns it (`gui.get_node`, `render.render_target`, `resource.create_buffer`, …) and thread that value through. There is no constructor and no meaningful cast across handle kinds — if you find yourself casting, the call you are feeding it almost certainly wants a different handle.

**Named handle types.** Each handle is also referenceable as a named type alias under its namespace — `render.render_target`, `render.constant_buffer`, `render.texture`, `socket.master`, `socket.client`, `socket.unconnected`, `b2d.b2World`, `b2d.b2Body` — so you can annotate a binding directly (`const rt: render.render_target = render.render_target("rt", {})`). The alias resolves to the same `Opaque<"<token>">` brand the handle-returning function yields, so the annotation and the returned value are the same nominal type.

**How we pin this in the type tests.** `packages/types/test-d/ambient.ts` passes an `Opaque<"constant">`-typed value to `model.play_anim` and asserts a bare `0` in the same slot carries `@ts-expect-error`. It also binds `render.render_target(...)` to a `render.render_target`-typed variable and asserts a bare `0` cannot be — proving the named alias and the function's return type share one brand. If the brand is dropped or widened to `unknown`, the expected errors disappear and the typecheck gate fails.

#### Callback parameters type-check as functions, not `unknown`

**Symptom.** Engine APIs that take a callback (`timer.delay`, `msg`-style message handlers, `http.request`, factory/particlefx completion callbacks, …) now expect a function of a specific arity. Passing a non-function, or a function with the wrong number of parameters, is a type error:

```ts
timer.delay(0.5, false, () => print("tick"));                       // too few params — TS error
timer.delay(0.5, false, (self, handle, time_elapsed) => { });       // OK — three params
```

**Why.** Defold's ref-doc names a callback parameter by its whole Lua signature string, e.g. `function(self, handle, time_elapsed)`. The generated typings recover each into an arity-preserving function type with the documented parameter names: `(self: unknown, handle: unknown, time_elapsed: unknown) => void`. The parameter names survive for hover documentation, but their types are `unknown` — the ref-doc carries no inner types — so you must narrow each argument yourself before using it. The return is `void`: the engine ignores any value a callback returns, and a `void` return position still accepts a callback that happens to return something.

**Typed alternative.** Match the documented arity and read the parameter names off hover to know what each slot is. Cast or narrow the `unknown` params at the point of use (`const url = result as Url`), exactly as you would any other `unknown`.

#### Some slots are `unknown` on purpose — the `any` wildcard

**Symptom.** A few API slots are typed `unknown`: they accept any value going in, and a value coming out cannot be used until you narrow it.

```ts
const [first] = socket.skip(1, "a string", 42);  // first is `unknown`
const n: number = first;                          // TS error — narrow it first
const n2 = first as number;                       // OK
```

**Why.** Where Defold's own ref-doc types a value as the bare `any` token — "any Lua value" — the generated typings use `unknown` rather than guessing a concrete type. `socket`'s utilities (`socket.skip`) and its option accessors (`getoption`/`setoption`) are the cases you will meet. This is deliberate, not a gap: `unknown` is the honest model for "could be anything." It accepts everything as an argument, and as a result it forces a check before use — unlike TypeScript's `any`, which would silently switch type-checking off for that value.

**Typed alternative.** Treat these exactly like callback parameters: narrow or cast at the point of use (`first as number`), guided by what the Defold API docs say the value is. A branded or nominal type would be wrong here — the whole point of the `any` token is that no single concrete type fits.

**How we pin this in the type tests.** `packages/types/test-d/socket-any-unknown.ts` passes assorted values into `socket.skip`'s wildcard slots (proving any argument is accepted) and asserts a wildcard return is not directly assignable to `number` via `@ts-expect-error`, while a narrowing cast is. If a wildcard slot ever widened to `any` or were mis-mapped to a concrete type, the expected error would flip and the typecheck gate would fail.

#### `if (x)` truthiness differs — `0` and `""` are truthy in Lua

**Symptom.** A guard that reads naturally in TypeScript changes meaning after transpile. `if (count)` in TS is false for `0`; the Lua it becomes is true for `0`.

```ts
function describe(count: number, label: string): string {
  if (count) {            // transpiles to `if count then` — true even when count is 0
    return label;
  }
  return "empty";
}
```

**Why.** `if (x)` transpiles to `if x then`, a direct pass-through with no coercion. JavaScript and Lua disagree on what counts as falsy: JS treats `0`, `""`, `NaN`, `null`, and `undefined` as falsy; Lua treats **only** `nil` and `false` as falsy. So `0` and `""` — falsy in the TypeScript you wrote — are **truthy** in the Lua that runs. The type system cannot warn you: the code is well-typed in both directions.

**Typed alternative.** Test the value you actually mean. Use `if (count > 0)`, `if (label !== "")`, or `if (x !== undefined)` instead of relying on truthiness. An explicit comparison transpiles to the same comparison in Lua and means the same thing in both languages.

**How we pin this in the type tests.** `packages/transpiler/src/narrowing-transpile.test.ts` snapshots `transpile(...)` of an `if (x)` guard and asserts the committed Lua is `if x then` — no coercion inserted. If [TypeScriptToLua](https://typescripttolua.github.io/) (TSTL) ever started wrapping the condition in a JS-truthiness helper, the snapshot would change and the gate would fail.

#### `typeof` cannot narrow engine values — they are Lua `userdata`

**Symptom.** A `typeof` guard that should match a Defold handle never fires at runtime, even though it type-checks.

```ts
function asNode(x: unknown): unknown {
  if (typeof x === "object") {   // transpiles to `type(x) == "table"` — false for a gui.node
    return x;
  }
  return undefined;
}
```

**Why.** `typeof x === "object"` transpiles to `type(x) == "table"`. Defold engine values — `gui.node`, `texture`, `buffer`, `b2World`, … — are Lua `userdata`, not tables, so `type(handle)` returns `"userdata"` and the branch is skipped. The value form is no better: `typeof x` transpiles to `__TS__TypeOf(x)`, which returns the string `"userdata"` for these handles — a value TypeScript's `typeof` union (`"object"`, `"function"`, `"number"`, …) does not even contain, so you cannot write a matching comparison. `typeof x === "number"/"string"/"boolean"/"function"` *do* inline to a reliable `type(x) == "…"`, and those work as written; it is only objects-vs-userdata that breaks.

**Typed alternative.** Do not reach for `typeof` to recognise an engine handle. The handles are already nominally typed (`Opaque<"node">` and friends — see [Engine handles are opaque](#engine-handles-are-opaque--you-cannot-fabricate-or-cast-across-kinds)), so thread the typed value through instead of re-checking it. When you genuinely hold an `unknown` from a wildcard slot, narrow it with the engine predicate that fits (a `nil` check, a field probe) rather than `typeof`.

The one runtime narrowing the engine *does* support for vmath userdata is the `types.is_*` family, emitted as user-defined type guards:

```ts
declare const v: unknown;
if (types.is_vector3(v)) {
  // v is Vector3 here — v.x is a number, no cast needed
  const x = v.x;
}
```

`types.is_hash`, `types.is_url`, `types.is_matrix4`, `types.is_quat`, `types.is_vector`, `types.is_vector3`, and `types.is_vector4` each narrow their argument to the matching core type. The other `is_*` / `exists` names (`go.exists`, `sound.is_music_playing`, …) are runtime-state checks on an already-typed value, not type guards, so they stay `boolean`.

**How we pin this in the type tests.** `packages/transpiler/src/narrowing-transpile.test.ts` snapshots both forms: `typeof x === "object"` → `type(x) == "table"`, and the value form `typeof x` → `__TS__TypeOf(x)`. The committed Lua makes the userdata mismatch visible; if either lowering changed, the snapshot would fail.

#### `on_message` ids are hashes, not strings

**Symptom.** A handler that compares `message_id` against a string literal never fires, even though it reads naturally and (under older typings) compiled. The object it should react to is silently ignored — in the platformer example, the player fell through every wall because the contact handler never ran.

```ts
on_message(self, message_id, message) {
  if (message_id == "contact_point_response") {  // never true at runtime
    // ...
  }
}
```

**Why.** Defold delivers `message_id` to `on_message` as a pre-hashed `hash` value, not a string — the same way `action_id` arrives in `on_input`. Lua's `==` does no cross-type coercion, so `hash_value == "contact_point_response"` is always `false`. The string comparison transpiles verbatim (`message_id == "contact_point_response"`) and silently never matches. `ScriptHooks.on_message` types `message_id` as `Hash` to make the mismatch a *compile* error rather than a runtime mystery; the string-literal form no longer type-checks.

**Typed alternative.** Pre-hash the id once at module scope and compare `Hash` to `Hash`, exactly as the original Lua does and as `on_input` already does for `action_id`:

```ts
const msg_contact_point_response = hash("contact_point_response");

on_message(self, message_id, message) {
  if (message_id == msg_contact_point_response) {
    const contact = message as unknown as ContactPoint;  // handler payload is an untyped record
    // ...
  }
}
```

The handler's `message` is an untyped `Record<string | number, unknown>` — cast it to the subset you read. Sender-side payload narrowing by message id lives on `msg.post` (see the [messages guide](./messages.md)), not on the handler.

**How we pin this in the type tests.** `packages/types/test-d/lifecycle.ts` binds `message_id` to a `Hash` inside the handler and asserts a string-literal `message_id` at the call site carries `@ts-expect-error`. If `on_message` ever re-typed the id as a string, the expected error would disappear and the typecheck gate would fail.

#### `window.set_listener` hands `event` and `data` as separate params

**Symptom.** A `window.set_listener` callback reads the resize dimensions off `data`, but `data.width` does not type-check (or is `unknown`) even after checking `event == window.WINDOW_EVENT_RESIZED`:

```ts
window.set_listener((self, event, data) => {
  if (event == window.WINDOW_EVENT_RESIZED) {
    print(data.width, data.height);  // data stays a record — width/height not known
  }
});
```

**Why.** The engine delivers `event` and `data` to the callback as two **separate** parameters, and the `WINDOW_EVENT_*` constants are branded numbers. TypeScript never correlates two independent parameters, and a branded number is not a unit-type discriminant — so an `event == …` check cannot auto-narrow `data` the way a discriminated-union field would. The generated callback types `event` as the union of the five `WINDOW_EVENT_*` constants (so you get autocomplete and simple positive `event ==` narrowing) and `data` as a bare `Record<string | number, unknown>` (only a resize carries fields, so the record is the honest default).

**Typed alternative.** Use the provided `isWindowEvent` guard — the window mirror of [`isMessage`](messages.md#receiving-messages-with-type-narrowing). It re-introduces the discriminant at the use site and narrows the untyped `data` to that event's payload:

```ts
window.set_listener((self, event, data) => {
  if (isWindowEvent(event, data, window.WINDOW_EVENT_RESIZED)) {
    print("resized:", data.width, data.height);  // data: { width: number; height: number }
  }
});
```

`isWindowEvent` is declaration-only: the transpiler lowers the call to a bare `event == window.WINDOW_EVENT_RESIZED`, so there is no runtime function and no import to add. Only `WINDOW_EVENT_RESIZED` carries fields; every other event narrows `data` to `undefined`. This is the same wall — and the same fix — as [`on_message` ids](#on_message-ids-are-hashes-not-strings): the engine hands back an untyped payload discriminated by a separate id/event argument, and a declaration-only guard is the path to a typed payload.

#### `null`, `undefined`, and `== null` all collapse to `nil`

**Symptom.** Three TypeScript checks you might think are distinct produce one identical Lua test, so they cannot be told apart at runtime.

```ts
function present(x: unknown): boolean {
  if (x === null) return false;       // `x == nil`
  if (x === undefined) return false;  // `x == nil`
  return true;
}
```

**Why.** Lua has a single absent value, `nil`. TypeScript's `null`, `undefined`, the strict `x === null` / `x === undefined`, and the loose `x == null` all transpile to `x == nil`. There is no Lua-level distinction between "explicitly null" and "missing", so a function that tries to treat `null` and `undefined` differently cannot — both arrive as `nil`. The `=== nil` form (using the ambient `nil` type) works as written and is the honest model.

**Typed alternative.** Model absence with a single sentinel. Pick `undefined` in your TypeScript (it is what the engine's `nil` maps to most naturally), use `x === undefined` or `x == null` to test it, and do not design APIs that depend on distinguishing the two. If you need a third "unset" state, encode it explicitly with a value, not with `null`-vs-`undefined`.

**How we pin this in the type tests.** `packages/transpiler/src/narrowing-transpile.test.ts` snapshots `x === null` and `x === undefined` side by side and asserts both committed lines are `x == nil`. The collapse is visible in the snapshot; if [TypeScriptToLua](https://typescripttolua.github.io/) (TSTL) ever distinguished them, the gate would fail.

#### `===` and `==` compile to the same Lua — strictness is a convention, not a runtime guard

**Symptom.** Coming from JavaScript you might assume `==` performs loose equality — coercing its operands before comparing — and reach for `===` to avoid it. In this toolchain the two operators are indistinguishable in the output, so the coercion `===` guards against never happens.

```ts
function isEmpty(cell: number): boolean {
  const strict = cell === 0;   // → `cell == 0`
  const loose = cell == 0;     // → `cell == 0` (byte-identical)
  return strict || loose;
}
```

**Why.** TypeScriptToLua emits Lua `==` for **both** operators and never inserts a coercion helper, and Lua `==` is already non-coercing. The one runtime distinction JavaScript draws between the two — loose equality's coercion, including `== null` matching both `null` and `undefined` — is moot here as well, because `null` and `undefined` both collapse to `nil` (see [`null`, `undefined`, and `== null` all collapse to `nil`](#null-undefined-and--null-all-collapse-to-nil)). So `===` buys no runtime safety the `==` form lacks; strictness is a source convention, not a guard. Contrast `if (x)` truthiness (see [`if (x)` truthiness differs](#if-x-truthiness-differs--0-and--are-truthy-in-lua)), which *is* a real change of meaning crossing into Lua.

**Typed alternative.** The scaffolded `biome.json` ships with `noDoubleEquals` off precisely because the operators are identical in the Lua output, so use whichever reads best — `===` is no longer enforced for consumers. (Our repo keeps the rule on as house style; its `== null` exemption also preserves one genuinely useful loose form — `x == null` narrows out both `null` and `undefined` in TypeScript's type-checker, a *compile-time* distinction even though the emitted Lua is identical.) The real equality footgun is never `==` versus `===`; it is `if (cell)`, which is truthy for `0` once it runs as Lua.

**How we pin this in the type tests.** `packages/transpiler/src/narrowing-transpile.test.ts` transpiles `cell === 0` and `cell == 0` in one snippet and asserts both lower to the same `cell == 0` — the loose form gets no coercion helper. If [TypeScriptToLua](https://typescripttolua.github.io/) (TSTL) ever started coercing `==`, the two lines would diverge and the gate would fail.

#### `as` is a compile-time assertion, not a runtime check

**Symptom.** A cast that compiles cleanly does nothing at runtime — the value is never validated, and a wrong assertion produces a silent type mismatch later, not an error at the cast.

```ts
function first(values: unknown): number {
  const n = values as number;   // transpiles to `local n = values` — no check
  return n + 1;                 // runs even if `values` was a string or a table
}
```

**Why.** `const n = first as number` transpiles to `local n = first`: the cast is erased entirely. TypeScript's `as` is a *compile-time* assertion that you, the author, know the type — it inserts no runtime guard. So a cast that is wrong does not throw at the cast site; the bad value flows on until some Lua operation on it misbehaves, far from the cause. This is the same erasure that makes branded constants and opaque handles zero-cost — useful there, a footgun when you use `as` to "convert" an `unknown`.

**Typed alternative.** When you actually need to *check* a value (a wildcard `unknown`, untrusted input), narrow it with a real runtime test — `typeof x === "number"` (reliable for primitives, see the `typeof` entry above), a `=== nil` check, or a field probe — before using it. Reserve `as` for the cases where you already know the type from context the type system can't see, exactly as with callback and wildcard params.

**How we pin this in the type tests.** `packages/transpiler/src/narrowing-transpile.test.ts` snapshots `const n = x as number` and asserts the committed Lua is `local n = x` with no inserted check. If a cast ever started emitting a guard, the snapshot would change and the gate would fail.

#### Component properties are catalogued per namespace

**Symptom.** Defold component properties — the values you address at runtime through `go.get`/`go.set`/`go.animate` with a string id (`"color"`, `"position"`, `"size"`, …) — do not appear as members on the namespace object. There is no `label.color` you can read directly.

**Why.** These properties are not module-level globals; they are per-component fields keyed by a string id passed to `go.get(url, "color")`. The ref-doc lists them as `PROPERTY` elements with a name and a type but no addressable symbol. The generated typings recover each namespace's properties into an in-namespace `interface properties { … }` so the name and type survive as a committed, drift-gated catalog. For example, `label.properties` carries `color: Vector4`, `size: Vector3`, `scale: number | Vector3`, and so on.

**Typed alternative.** Read a property's type off the catalog with an indexed access — `label.properties["color"]` is `Vector4`. The catalog also makes `go.get`/`go.set` type-aware: a literal key drawn from `go`'s own transform properties narrows the result and the written value to the property's real type. `go.get(url, "position")` is `Vector3`, `go.get(url, "scale")` is `number`, and `go.set(url, "euler", v3)` type-checks while `go.set(url, "position", "oops")` is rejected. Any other key — a `Hash`, a dynamic string, or a fragment-addressed cross-component property like `go.get("#sprite", "tint")` — falls through to an open `string | Hash` overload returning the documented wide union, so hashed and runtime access keep working unchanged.

**Name the component to narrow a cross-component property.** A string url like `"#sprite"` cannot tell the type system which component it targets, so the bare call can only narrow `go`'s own transform properties. When you know the component, name it with a type argument and the result narrows to *that* component's catalog:

```ts
const animation = go.get<sprite.properties>()("#sprite", "animation"); // Hash, not the wide union
go.set<sprite.properties>()("#sprite", "playback_rate", 2);            // value gated to number
go.get<sprite.properties>()("#sprite", "nope");                       // type error — not a sprite property
```

The form is curried — `go.get<P>()(url, property)` — on purpose. TypeScript has no partial type-argument inference: if `P` and the property key were both type parameters on one call, supplying `<sprite.properties>` would force the key to its default and collapse the return to the component's whole value union. The empty `()` fixes `P`, then the inner call infers the key from the `"animation"` argument, recovering the exact field type. You are naming the component yourself — nothing checks that `"#sprite"` actually resolves to a sprite — so this is a typed convenience over an unverified url, not a correctness guarantee. The bare direct call (`go.get("#go", "position")`) is unchanged for the transform default, and a fully dynamic key still falls through to the wide union.

**Name the script to read or tune another object's declared properties.** The same generic also types the *cross-script* channel — reading or writing a property a *different* script declared, addressed by its script-component url (`go.get("/enemy#controller", "speed")`). This is distinct from a component property and from the `self`-side access inside the owning script: it is how one object tunes another object's declared state. A script declares its editor properties with the value-keyed `properties` field of `defineScript`, and exports that shape as a nameable type with `ScriptPropertiesOf<typeof script>`; another script names it as the `P` generic to get a typed read and a value-gated write:

```ts
// enemy.ts — the owning script declares its properties
export default defineScript({
  properties: { speed: 100, target: vmath.vector3() },
});
export type EnemyProps = ScriptPropertiesOf<typeof import("./enemy").default>;

// elsewhere — another object reads and tunes them by url
const speed = go.get<EnemyProps>()("/enemy#controller", "speed");  // number
go.set<EnemyProps>()("/enemy#controller", "speed", 250);           // value gated to number
go.get<EnemyProps>()("/enemy#controller", "missing");              // type error — not declared
```

`ScriptPropertiesOf` extracts the same `TProps` the owning script's `self` carries, so the cross-script type and the owning script's `self` stay one source of truth — there is no second hand-maintained interface to drift. As with the component generic, you name the script yourself; nothing verifies the url resolves to that script.

**How we pin this in the type tests.** `packages/types/test-d/guide-snippets.ts` asserts `label.properties["color"]` is assignable to `Vector4` and that a `string` annotation on the same member carries `@ts-expect-error`. `packages/types/test-d/go-property-accessors.ts` pins the typed `go.get`/`go.set`: narrow keys resolve to `Vector3`/`Quaternion`/`number`, a wrong-typed `go.set` value and a wrong-typed `go.get` assignment carry `@ts-expect-error`, and the `Hash`/dynamic-string fallback still type-checks. `packages/types/test-d/go-property-access.ts` pins the caller-named-component generic: `go.get<sprite.properties>()("#sprite", "animation")` is `Hash`, a wrong key and a wrong value type carry `@ts-expect-error`, and the bare transform call still resolves; it also pins the cross-script channel — a `ScriptPropertiesOf<typeof enemyScript>`-named read is typed, a write is value-gated, and a wrong key or wrong value type carries `@ts-expect-error`. `packages/types/test-d/lifecycle.ts` proves `ScriptPropertiesOf` extracts exactly the declared property shape (excess and wrong-typed fields carry `@ts-expect-error`), tying it to the `self` channel. If the property catalog is dropped, its member types change, or the overloads regress, one of these lines flips and the typecheck gate fails.

#### Field-documented tables are typed object shapes, not opaque records

**Symptom.** A `table` param or return whose Defold ref-doc spells out its fields, or whose official example proves a stable shape, is no longer the opaque `Record<string | number, unknown>` it once was. `sys.get_sys_info()` returns a concrete object — `system_name`, `gmt_offset`, and the rest are typed members you can read directly and that auto-complete; a misspelled field is a compile error, not silent `unknown`.

```ts
const info = sys.get_sys_info();
const name: string = info.system_name;   // typed string, no cast
const offset: number = info.gmt_offset;  // typed number
// @ts-expect-error not_a_field is not a field of the sys info table
info.not_a_field;
```

**Why.** Many Defold `table` slots carry their field structure only in the doc HTML, in one of four regular shapes: a `<dt><code>field</code></dt><dd><span class="type">T</span></dd>` definition list, a `<ul>` whose items read `<span class="type">T</span> <code>field</code>` (type before name), a dash-list option bag whose items read `field <span class="type">T</span>` / `<code>field</code> <span class="type">T</span>` (name before type), or a code-dash field that reads `<code>field</code> - <span class="type">T</span>` (name in `<code>`, then dash, then type — `sys.open_url`'s `target` attribute). The generator parses these shapes and emits an inline object type instead of the `Record` fallback, so the field names and types survive. Two nested shapes are also recovered: a `<dl>` declaring a single `table`-typed field whose keys sit in an immediately-following `<ul>` typed-field list (`window.get_safe_area()` now returns `{ safe_area: { x: number; y: number; … } }`), and a flattened `<ul><li><dl>` option bag whose `table` entries are followed by their member fields (`resource.create_atlas` groups `animations` and `geometries` into nested objects). A recovered `table` field whose `<dd>` prose reads "a list of …" emits an **array** of that recovered element shape rather than a single object (`resource`'s `animations` and `create_atlas`'s `geometries` become `{ … }[]`); the `[]` is appended only when member fields were recovered. A "list" field with no recovered member shape but a machine-readable **numeric** element type — its `<dd>` reads "a list of … in the form {px0, py0, …}" / "{i0, i1, …}", a flat comma-separated list of numeric placeholders — emits `number[]` (`resource.create_atlas`/`set_atlas`'s `vertices`/`uvs`/`indices`); a brace form with quotes, nested braces, or non-numeric identifiers is never guessed and stays `Record`. A "list" field with neither members nor a numeric brace form (opaque maps, the wholesale `geometries` `Record`) stays `Record`. A cross-reference form is also recovered: a `table` slot with no inline field list of its own whose doc carries a `See <a href="…#<element>">` pointer to a sibling element in the same module adopts that element's already-recovered fields (`physics.set_shape`'s data param adopts `physics.get_shape`'s fields). Resolution is one hop only. A supplementary `See` pointer sitting beside an **untyped name-only** `<ul>` field list (`<li>field</li>` items with no `<span class="type">`) is also recovered: the slot adopts the referenced element's fields **filtered to the names the own `<ul>` enumerates** (`resource.get_atlas` lists `texture`/`geometries`/`animations` then points at `resource.set_atlas`, so it adopts those three only — the sibling's unlisted `vertices`/`uvs`/`indices` are excluded). A `See` pointer beside an element's own **typed** field list still loses to the direct parse, which already recovers those fields. Tables with no recoverable shape (the wholesale `geometries` `Record`, opaque key→value maps) keep the `Record` type — there is no single machine-readable structure to recover. Two deliberate distinctions: a recovered **input** parameter's fields are optional (an option bag accepts a partial or empty `{}`, exactly as the old `Record` did), while a **return** table's fields are required (the engine always populates them); and recovery nests at most one level — a deeper `table` field with no recovered keys stays `Record`.

**Typed alternative.** Read the members directly — `sys.get_sys_info().system_name`, `liveupdate.get_mounts()[0].uri`, `tilemap.get_tile_info(url, layer, x, y).index` — instead of indexing an opaque record and casting. For an options argument, pass only the fields you need (`image.load(data, { flip_vertically: true })`); omitted fields and `{}` still type-check.

**How we pin this in the type tests.** `packages/types/test-d/sys-info-table-fields.ts` asserts `sys.get_sys_info().system_name` is assignable to `string` and that a bogus field carries `@ts-expect-error`; `packages/types/test-d/example-shaped-table-curations.ts` pins the example-proven `liveupdate.get_mounts()` and `tilemap.get_tile_info()` shapes. The fidelity audit and the emitter share the table recovery and curation data (`packages/types/src/emit-dts.ts`), so the `recordTables` loss gate and the emitted surface cannot drift; if a recovered field's type regressed to `unknown` the audit's `unknownTokens` would surface it.

#### `async`/`await` work but there is no event loop

**Symptom.** You can write `async` functions, `await`, and `Promise` (the `Promise` type ships in the ES2022 lib), and it type-checks and transpiles. What does **not** exist is a JavaScript event loop: there is no `setTimeout`, no I/O microtask queue, and no scheduler that drains pending promises between frames. A promise advances only when something resolves it synchronously on the current call stack.

```ts
async function rollLater(): Promise<number> {
  return 42; // resolves synchronously
}

export async function main(): Promise<void> {
  const r = await rollLater(); // runs to completion in the same call
  print(r);
}
```

**Why.** TypeScriptToLua implements `async`/`await` itself, on top of Lua coroutines:

- An `async function` is lowered to `__TS__AsyncAwaiter(generator)`, which returns a `__TS__Promise` and runs the function body inside a Lua **coroutine**.
- `await x` is lowered to `__TS__Await(x)`, which yields the value through the body's Lua coroutine. The awaiter wraps the yielded value as `Promise.resolve(x)`, registers a continuation, and `coroutine.resume`s the body with the result once that promise settles.
- `__TS__Promise` is TSTL's own Lua class with `then`/`catch`/`finally`/`all`/`resolve`/`reject`. Resolution is callback-based and synchronous: a callback registered on an already-settled promise fires immediately; otherwise it is stored until `resolve()`/`reject()` is called.

These helpers ship in `lualib_bundle.lua`, which the build writes to the output root; the emitted module does `require("lualib_bundle")` to pull them in. No setup or polyfill is needed.

The consequences are where it bites:

- Awaiting an already-resolved or synchronously-resolving promise runs to completion in the same frame — fine, and reads well.
- There is no timer or I/O integration. `await new Promise((r) => setTimeout(r, 1000))` cannot be written with a *global* `setTimeout` — there is none, so a bare call is a compile error (TS2304, *Cannot find name 'setTimeout'*), not a silent runtime failure. Import one from `@defold-typescript/types/timers` instead (see **Importable polyfills** below). A promise that nobody resolves leaves the async function suspended **forever**, with no error and no warning.
- A rejected promise with no `.catch` is silently dropped; there is no Node-style "unhandled rejection" report.

**The engine scheduler bridge.** What the JS runtime lacks — a thing that advances pending work between frames — Defold supplies as `timer.delay`: a frame-driven scheduler that fires a callback on a later frame. That callback is the hook. Resolve a `Promise` from inside a `timer.delay` callback and the `await` waiting on it resumes when the engine fires the timer, not before. Bridge it by hand by stashing the promise's `resolve` and calling it from the callback:

```ts
function waitSeconds(seconds: number): Promise<void> {
  return new Promise<void>((resolve) => {
    timer.delay(seconds, false, () => resolve()); // engine callback drives the promise
  });
}
```

**Importable polyfills.** You do not have to hand-roll that bridge. The first timer-polyfills slice ships it as named module exports:

```ts
import { setTimeout, setInterval, clearTimeout, clearInterval, wait } from "@defold-typescript/types/timers";
```

`setTimeout`/`setInterval` take **milliseconds** (the web-familiar unit) and return a numeric `timer` handle; pass that handle to `clearTimeout`/`clearInterval` — or to Defold's own `timer.cancel`, which is the same handle. `wait` takes **Defold-native seconds** and returns a `Promise<void>` you can `await`:

```ts
import { wait } from "@defold-typescript/types/timers";

export async function main(): Promise<void> {
  await wait(1); // resumes when the engine timer fires, not before
  print("one second later");
}
```

These are not ambient globals: each script is an isolated Lua chunk with no shared scope, so the import lowers to a `require` of the timer runtime the build writes to the output root (the same mechanism as `lualib_bundle`). Because there is no global, a bare `setTimeout(...)`/`setInterval(...)` (the muscle-memory web form) is a **compile error** — `TS2304: Cannot find name 'setTimeout'` — under the scaffolded `lib: ["ES2022"]` surface (no DOM/Node globals). That error is the warning: add the `import { setTimeout, … } from "@defold-typescript/types/timers"` line and it resolves. Your editor does this for you — tsserver lists the timers module in autocomplete and offers an *Add import from "@defold-typescript/types/timers"* quick-fix on the `TS2304` squiggle, so the fix is one keystroke (works in any tsserver-backed editor; no extension needed). Do not "fix" it by widening `lib` to `"DOM"` or adding `@types/node` — that would restore a global `setTimeout` declaration that type-checks but has no runtime behind it in Defold, turning the honest compile error into a silent forever-suspended `await`.

**Caveats.** The polyfills are timer-backed, not a drop-in `setTimeout`. Four differences bite:

- **Context-bound lifetime.** A `timer.delay` timer is owned by the script that created it and is auto-cancelled when that game object is deleted. A `wait` straddling the deletion of its own object never resolves.
- **One-frame minimum resolution.** Even `setTimeout(cb, 0)` / `wait(0)` fires on the *next* frame, never the same one — the scheduler is frame-driven, so sub-frame delays round up to one frame.
- **No microtask queue.** `Promise.resolve().then(...)` still runs synchronously on the current call stack; there is no microtask drain. Only a *timer-backed* promise crosses a frame boundary.
- **Leaked suspended coroutines.** A promise that nobody ever resolves leaves its `async` function suspended forever as a parked Lua coroutine — no error, no warning, no timeout.

**ts-defold contrast.** ts-defold ships no `setTimeout` polyfill of its own — its only `settimeout` is LuaSocket's per-socket I/O timeout method, not a scheduler. The `@defold-typescript/types/timers` module is specific to this toolchain.

**How we pin this in the type tests.** `packages/transpiler/src/transpile.test.ts` transpiles an `async`/`await` sample and asserts the lowering (`__TS__AsyncAwaiter` for the function, `__TS__Await` for the await) with zero diagnostics, and that the Promise runtime (`__TS__Promise`) is present in the emitted `lualib_bundle`. If [TypeScriptToLua](https://typescripttolua.github.io/) (TSTL) changed the async lowering or stopped bundling the Promise helpers, the assertions would fail.

#### URL addressing: same-world objects are relative, `socket:` crosses worlds

**Symptom.** A `msg.post` that reads naturally in TypeScript silently fails to reach its target — the receiver's `on_message` never fires, and nothing compiles wrong. The same applies to every API that takes a URL string (`go.get`/`go.set`, `msg.url`, `factory.create`, …). A literal socket copied from a Lua manual example, like `"main:/manager#controller"`, is the usual culprit: it resolves only when the target collection is actually *named* `main`.

```ts
msg.post("main:/enemy#ai", "alert");            // resolves only if the target collection's Name is "main" — fragile
msg.post("/enemy#ai", "alert");                 // robust: absolute path inside the current world
msg.post("#health", "damage", { amount: 10 }); // sibling component on the same game object
```

**Why.** A Defold URL is `[socket:][path][#fragment]` — three parts, the first optional. The `path` is the target object's id, the `#fragment` is the component on it, and an address that **starts with `/` is resolved from the root of the current game world** (the bootstrap collection loaded at game start). The `socket:` segment names *which game world* the target lives in, and it earns its keep only with collection proxies: a world's socket name is the **`Name` property of its collection file** — "The new world gets its name from the *Name* property in the collection file." The bootstrap collection is named the same way (it too is given a unique name from *its* `Name` property), so there is no special socket you address it through — inside that one world you never write the `socket:` segment at all. The trap is that a collection's `Name` is a property distinct from its folder: the editor's `main/main.collection` is a *file path*, while the `Name` you address the world by is a separate field (commonly the project default `default`, not `main`). So a literal `"main:…"` borrowed from a manual example breaks the moment your bootstrap collection is named anything other than `main`. The two-arg form `msg.url(socket, path, fragment)` is a separate runtime trap — only the no-arg, one-string, and three-arg forms are runtime-supported, so `msg.url("main", "camera")` is a runtime error. The tightened `msg.url` overloads in `packages/types/src/msg-overloads.d.ts` reject that two-arg call at compile time, so the typings are the warning.

**Typed alternative.** For anything in the **same world** (everything in your bootstrap collection) address it without a socket: `"camera"` (a sibling instance by id, relative to the current component), `"/camera"` (the same instance by id, absolute from the world root), or `"#health"` (a sibling component on the same game object). Reserve `socket:` for reaching into a **collection-proxy-loaded** world, and pass the *target* collection's `Name` — the collection-proxy manual's own cross-world example is `msg.post("mylevel:/myobject", "hello")`, where `mylevel` is the loaded collection's `Name`, not the proxy component's id. For `msg.url`, use one of the three typed overloads — `msg.url()` (the current message's url), `msg.url("main:/manager#controller")` (one string), or the all-required `msg.url(hash("level1"), hash("/door"), hash("script"))` — never the two-arg form.

**How we pin this in the type tests.** `packages/types/test-d/msg-url-arity.ts` asserts the tightened `msg.url` overloads — `msg.url()` and `msg.url("main:/manager#controller")` type-check, while the two-arg `msg.url("main", "camera")` carries `@ts-expect-error` — so the runtime-invalid arity is rejected at compile time; widen the overloads to accept it and the expected error vanishes, failing the typecheck gate. The prose pins — this section's heading, its front-digest link, and the `agent-runbooks.md` runbook — are asserted structurally in `packages/types/test/guide-docs.test.ts`.

### Data structures: what's built in

TypeScript ships a richer set of containers than Lua's single `table`, and the toolchain lowers each one to code Defold's Lua 5.1 VM runs. Most of them lower to a plain Lua table; the ones with behaviour (`Map`, `Set`, `class`, spread) lean on runtime helpers that TypeScriptToLua emits into `lualib_bundle`. That bundle is pure Lua 5.1 the CLI writes to the output root, pay-for-use: a container that needs a helper pulls it in, the rest cost nothing. Every container below runs unchanged on Defold's VM (LuaJIT on native and desktop, a 5.1 VM on HTML5).

This page is the full availability map. For the Lua-to-TypeScript container translation at cheat-sheet depth — which `table` shape becomes which TypeScript type — see [TypeScript vs Lua](./typescript-vs-lua.md#tables-vs-objects-arrays-and-maps).

The lowerings quoted below were captured by running the real transpile pipeline; the same shapes are pinned in `packages/transpiler/src/data-structures-transpile.test.ts`.

#### Built-in containers

| Structure | TypeScript form | Lowers to | Pulls `lualib`? | Use instead / note |
| --- | --- | --- | --- | --- |
| `Array` | `const xs: number[] = [1, 2, 3]` | Lua table `{1, 2, 3}` (1-based) | Literal, index, `push`, `length`: no. Higher-order methods (`map`, `filter`, `reduce`, …): yes | The idiomatic sequence. Keep arrays dense — holes desync `arr.length` from Lua's `#`. |
| tuple | `const t: [number, string] = [1, "a"]` | plain Lua table `{1, "a"}` | **No** | The cheapest container — a fixed-length, positional record. Prefer it over an object for a fixed pair. |
| `Map` | `new Map<string, number>()` | `__TS__New(Map)`; `.set`/`.get` call helper methods | Yes | Arbitrary (incl. non-string, object) keys. Use over an object record when keys are not fixed strings. On hot paths, `LuaMap` (below) is the same idea with no `lualib`. |
| `Set` | `new Set<number>()` | `__TS__New(Set)` | Yes | Membership and dedup. Prefer over scanning an array for "is `x` present". On hot paths, `LuaSet` (below) skips `lualib`. |
| `WeakMap` | `new WeakMap<object, V>()` | `__TS__New(WeakMap)` | Yes | Per-object side data whose entries vanish when the key is collected — caches keyed by object identity. |
| `WeakSet` | `new WeakSet<object>()` | `__TS__New(WeakSet)` | Yes | Weak membership — "have I seen this object" without pinning it alive. |
| object record | `{ x: 1, y: 2 }` | plain Lua table `{x = 1, y = 2}` | No (spread / `Object.entries` pull a helper) | Fixed, named string keys. The default for a struct; spread `{ ...a, y: 2 }` lowers to `__TS__ObjectAssign`. |
| `class` | `class C { … }` + `new C()` | `__TS__Class()` + `__TS__New`; table + metatable, methods on `prototype` | Yes | Real OO with inheritance. On hot paths a plain object or a closure is lighter — reach for `class` when you want a typed constructor and method dispatch. |

Two lowerings worth seeing in full. A tuple is just a table — no runtime helper, no `require`:

```ts
export const t: [number, string] = [1, "a"];
```

```lua
--[[ Generated with https://github.com/TypeScriptToLua/TypeScriptToLua ]]
local ____exports = {}
____exports.t = {1, "a"}
return ____exports
```

A `class`, by contrast, builds on the `lualib` runtime — `__TS__Class` makes the metatable-backed table and `__TS__New` instantiates it:

```ts
export class Counter {
  n = 0;
  bump(): void {
    this.n += 1;
  }
}
export const c = new Counter();
```

```lua
local ____lualib = require("lualib_bundle")
local __TS__Class = ____lualib.__TS__Class
local __TS__New = ____lualib.__TS__New
local ____exports = {}
____exports.Counter = __TS__Class()
local Counter = ____exports.Counter
Counter.name = "Counter"
function Counter.prototype.____constructor(self)
    self.n = 0
end
function Counter.prototype.bump(self)
    self.n = self.n + 1
end
____exports.c = __TS__New(____exports.Counter)
return ____exports
```

The `require("lualib_bundle")` only resolves at runtime because the CLI writes `lualib_bundle.lua` to the output root when any feature pulls it in. You never manage that file by hand.

#### Lower-overhead containers: the Lua table extensions

When a `Map` or `Set` sits on a hot path and the `lualib` `__TS__New` indirection matters, TypeScriptToLua's **language extensions** give you `LuaTable`, `LuaMap`, and `LuaSet` — thin, typed views over a raw Lua table that lower to direct indexing with **no `lualib`**:

```ts
const seen = new LuaSet<number>();
seen.add(1);
export const hit = seen.has(1);

const scores = new LuaMap<string, number>();
scores.set("a", 1);
export const a = scores.get("a");
```

```lua
--[[ Generated with https://github.com/TypeScriptToLua/TypeScriptToLua ]]
local ____exports = {}
local seen = {}
seen[1] = true
____exports.hit = seen[1] ~= nil
local scores = {}
scores.a = 1
____exports.a = scores.a
return ____exports
```

`LuaSet.add` becomes `t[v] = true`, `LuaMap.set`/`get` become plain `t[k] = v` / `t[k]`, and nothing pulls `lualib_bundle`. The trade is a deliberately thin surface: `get`/`set`/`has`/`delete` (plus `add` on the set), and that is all — no `.size`, no `for...of`, no insertion order. Reach for the standard `Map`/`Set` when you need to enumerate or count; reach for `LuaMap`/`LuaSet` when you only get, set, and test membership and want zero runtime overhead.

Use them as **ambient globals — do not import them.** `import { LuaMap } from "@typescript-to-lua/language-extensions"` is rejected (`… is not a module`) and silently falls back to the heavyweight `lualib` `Map`; written bare, `LuaMap`/`LuaSet`/`LuaTable` are part of the global type surface like the engine namespaces. (The Lua standard library itself — typed by `lua-types` — adds no container types beyond the universal `table`; these extension types are the typed way to use that raw table directly.)

#### Not available — reach for instead

A couple of genuine JavaScript built-ins do not survive the transpile to Lua 5.1. They type-check but fail at compile time, so you find out from `tsc --noEmit` / the transpile diagnostics, not at runtime.

| Want | Status | Reach for instead |
| --- | --- | --- |
| Regular expressions — `/b/`, `"x".match(/b/)` | **Rejected** — the diagnostic reads `string.match is unsupported.` | String methods: `indexOf`, `slice`, `startsWith`, `endsWith`, `includes`, `split`. They cover most parsing needs and lower to native Lua string ops. |
| `BigInt` — `1n` | **Rejected** — `Unsupported node kind BigIntLiteral` | A `number` (Lua's double holds integers exactly up to 2^53), or a string when you only format/transport the value. |

Regex is the one that bites most often. `"x".match(/b/)` type-checks but fails to transpile, because TypeScriptToLua maps `String.prototype.match` onto Lua's `string.match`, which takes a Lua pattern, not a JavaScript regex. Rewrite pattern checks with the string methods above; for anything more elaborate, parse by hand.

#### See also

- [TypeScript vs Lua](./typescript-vs-lua.md#tables-vs-objects-arrays-and-maps) — the container translation cheat sheet this page deepens.
- [Where script state lives](./script-state.md) — where to *put* these containers: per-instance `self`, a shared module local, or a module singleton.
- [TypeScript gotchas](./typescript-gotchas.md) — the runtime sharp edges (truthiness, `nil` collapse) that bite once the data is in a container.

### Script lifecycle helpers

`@defold-typescript/types` exports identity helpers for Defold script tables. They keep the runtime object unchanged while giving TypeScript a typed `self` and typed lifecycle hook parameters. `self` holds *per-instance* state; for the wider picture — when to reach for a shared module local, a cross-script module singleton, or a VM-global instead — see [Where script state lives](./script-state.md).

`init` **returns** the script's initial state, and that return is the single site TypeScript infers the `self` type (`TSelf`) from, so you write the field set once and every other hook's `self` is typed from it. (When you declare `properties`, `init` also *receives* a `self` holding just those property values — see [Script properties on `self`](#script-properties-on-self) — but the return is still the only state-inference site.) No explicit type argument is needed:

```ts
import { defineScript } from "@defold-typescript/types";

export default defineScript({
  init: () => ({ speed: 120 }),

  on_input(self, action_id, action) {
    if (action_id == null) {
      // No action_id = raw pointer/mouse-move event; read the cursor off `action`.
      const pointerX = action.x;
      const pointerY = action.y;
      void pointerX; // replace with real usage
      void pointerY; // replace with real usage
      return;
    }

    if (action.pressed) {
      self.speed += action.value ?? 0;
    }

    for (const touch of action.touch ?? []) {
      const finger = touch.id;
      const x = touch.x;
      void finger; // replace with real usage
      void x; // replace with real usage
    }
  },
});
```

Each source file is exactly one Defold script of one kind: you export a single factory call as `default`, never two in the same file, and a `.script` and a `.gui_script` are always separate files. A script with no `init` to infer `self` from — or one whose state you want to name up front — uses the explicit type-argument escape hatch instead, in its own file:

```ts
import { defineGuiScript, type Hash } from "@defold-typescript/types";

type MenuSelf = {
  root: Hash;
};

export default defineGuiScript<MenuSelf>({
  on_input(_self, action_id, action) {
    if (action_id == null) {
      // No action_id = pointer move; this menu handles only named actions, so bail.
      return;
    }

    if (action.released) {
      const text = action.text;
      void text; // replace with real usage
    }
  },
});
```

With an explicit type argument (`defineGuiScript<MenuSelf>`), `init`'s return is checked against `MenuSelf` rather than inferred from it.

#### Script properties on `self`

Declare editor script properties with the value-keyed `properties` field of `defineScript`. The key is the property name (written once) and the value is its default, so the value's type flows onto `self` alongside the state `init` returns. You never call `go.property` yourself — the transpiler synthesizes the chunk-scope `go.property(...)` registrations Defold needs:

```ts
import { defineScript, type Hash } from "@defold-typescript/types";

export default defineScript({
  properties: {
    adj: vmath.vector3(0, 0, 0), // self.adj: Vector3
    name: hash("initial value"), // self.name: Hash
  },
  init(self) {
    return { velocity: vmath.vector3(0, 0, 0).add(self.adj) };
  },
  update(self) {
    const name: Hash = self.name;
    self.velocity = self.velocity.add(self.adj);
    void name; // replace with real usage
  },
});
```

Property-backed fields are present on `self` before `init` runs, so they need not appear in `init`'s return. The state `init` returns is still checked on its own — an omitted state field remains a compile error, while omitted property-backed fields are correct.

##### Reading properties in `init`

Defold applies the declared property values to `self` *before* `init` runs, so `init` can read them at spawn time. Give `init` a `self` parameter and it is typed as the property channel — exactly the declared `properties`, for reading. This is the natural home for setup that depends on a property, such as playing the initial animation without waiting a frame:

```ts
import { defineScript, type Hash } from "@defold-typescript/types";

export default defineScript({
  properties: {
    start_anim: hash("idle"), // self.start_anim: Hash
    max_hp: 100, // self.max_hp: number
  },
  init(self) {
    // `self` here is only the property channel: start_anim and max_hp.
    sprite.play_flipbook("#sprite", self.start_anim);
    return { hp: self.max_hp };
  },
  update(self) {
    // Outside init, `self` is the merged properties + returned state.
    self.hp -= 1;
    void self.max_hp; // replace with real usage
  },
});
```

Inside `init`, `self` is **only** the property values — reading a field that is neither a declared property nor yet returned is a compile error. The return is still the sole state channel, and every other hook sees the merged properties-plus-state `self`.

> [!NOTE]
> Calling `go.property(...)` directly is deprecated. It still registers the property at runtime, but `self.<name>` stays untyped and the transpiler emits a build warning pointing you at the `properties` field — a reminder to move the property there.

Hovering `defineScript`, `defineGuiScript`, or `defineRenderScript` in the editor now shows the factory's purpose, the hooks each kind accepts (render scripts omit `on_input`), and a TypeScript example. Hovering an individual callback inside the hook table — `init`, `update`, `fixed_update`, `late_update`, `on_message`, `on_input`, `final`, `on_reload` — now shows that hook's Defold description and parameter docs as well. Hovering an `action` or `touch` field inside `on_input` — `action.value`, `action.pressed`, `touch.tap_count`, and the rest — shows that field's Defold description.

At runtime Defold owns `self` (a userdata-backed table) and a script can populate but not replace it, so the transpiler can't emit a returning `init` verbatim. It wraps the body in a builder and merges the returned table onto the engine `self`; a `nil`/stateless return merges nothing. When `init` takes a `self` parameter the builder receives the engine `self` (so a property read resolves to the real table), and the parameter keeps your name even if it is not literally `self`. The hooks you write stay in terms of a typed `self`.

`defineScript` and `defineGuiScript` both type `on_input` as `(self, action_id, action) => boolean | void`.

- `action_id` is `Hash | undefined`; Defold uses `nil` for pointer movement.
- `action` is `InputAction` with optional fields such as `value`, `pressed`, `released`, `x`, `y`, `text`, `marked_text`, and `touch`.
- `action.touch` entries are `InputTouch` values with fields such as `id`, `pressed`, `tap_count`, `x`, and `acc_x`.

`defineRenderScript` intentionally has no `on_input` hook because Defold render scripts do not receive input callbacks.

#### Frame-update hooks

Defold calls three per-frame hooks, all sharing the `(self, dt) => void` shape where `dt` is the time step in seconds:

| Hook           | When it runs                                                    |
| -------------- | --------------------------------------------------------------- |
| `update`       | every frame                                                     |
| `fixed_update` | every fixed physics step (only when fixed time step is enabled) |
| `late_update`  | every frame, after `update` and animation/physics have run      |

```ts
export default defineScript({
  init: () => ({ velocity: 0 }),
  update(self, dt) {
    self.velocity *= 1 - dt;
  },
  late_update(self, dt) {
    void dt; // replace with real usage
  },
});
```

#### Receiving messages: `on_message`

`on_message(self, message_id, message, sender)` runs when another script or the engine posts to this component. Defold pre-hashes the id, so `message_id` arrives as a `Hash` and `message` as an untyped record. `on_message`'s payload narrowing — the `isMessage` guard and the `onMessage` dispatcher that turn that untyped record back into its `BuiltinMessages` shape — is covered in [Typed messages](./messages.md), the same way [Where script state lives](./script-state.md) is the canonical home for `self` typing.

#### API availability by script kind

Defold scopes two namespaces to a script kind: `gui.*` resolves only inside a `.gui_script`, and `render.*` only inside a `.render_script`. Every other namespace (`go`, `msg`, `vmath`, `sys`, `physics`, …) is available in every kind.

The default `@defold-typescript/types` entrypoint aggregates *all* namespaces, so it never rejects a call the engine would allow at runtime — but it also can't catch a `gui.*` use in a plain `.script`. To get the engine's wall at compile time, pin the entrypoint matching the file's script kind in that file's `tsconfig`:

| Script kind      | `types` entrypoint                       | Namespaces           |
| ---------------- | ---------------------------------------- | -------------------- |
| `.script`        | `@defold-typescript/types/script`        | universal only       |
| `.gui_script`    | `@defold-typescript/types/gui-script`    | universal + `gui`    |
| `.render_script` | `@defold-typescript/types/render-script` | universal + `render` |

```jsonc
// tsconfig for a .gui_script source tree
{
  "compilerOptions": {
    "types": ["@defold-typescript/types/gui-script"]
  }
}
```

Under that config `gui.*` and the universal namespaces type-check while `render.*` is a compile error. The default `@defold-typescript/types` keeps every namespace, so the full surface is what you get everywhere until you opt in to a wall.

`init`, `build`, and `watch` never narrow the surface for you: they scaffold and build against whatever entrypoint your `tsconfig` names — the full `@defold-typescript/types` by default — and never add, remove, or prune a wall. Narrowing is **opt-in**, managed by the `wall` command: it narrows a single-kind source directory to its kind subpath with a composite `tsconfig.json` that `tsc -b --noEmit` enforces. See [Wall](wall.md) for the interactive menu, the flag forms, and the one constraint that makes a wall actually hold (import the lifecycle factory from the kind subpath, not the main entry).

### Typed messages

Defold delivers a message as a hashed id and a plain table, so the payload's shape is invisible to TypeScript by default. `@defold-typescript/types` restores it from both ends: `msg.post` checks the table you send against the built-in message's declared shape, and the `isMessage` guard — plus the `onMessage` dispatcher built on it — narrows a received `message` back to that shape. This page is the canonical home for that model; the `on_message` lifecycle callback itself is covered in [Script lifecycle](./script-lifecycle.md).

#### The message type surface

`BuiltinMessages` (generated in `packages/types/generated/builtin-messages.d.ts` from the Defold reference docs, not hand-maintained) maps each built-in message id to its payload shape, and `BuiltinMessageId = keyof BuiltinMessages` is the union of those ids. Both are ambient globals — no import. Because the catalog is regenerated from the ref docs rather than curated by hand, it is exhaustive: every message Defold documents is in it, so a valid built-in id always type-checks and a typo never does.

#### Sending: `msg.post` payload narrowing

A `msg.post(receiver, "<builtin id>", payload)` call checks `payload` against `BuiltinMessages["<id>"]`. Miss a required field or give one the wrong type and it is a compile error, not a silent runtime mismatch:

```ts
msg.post("#collisionobject", "apply_force", {
  force: vmath.vector3(0, 1000, 0),
  position: go.get_world_position(),
});
```

The narrowing keys on the literal id. An arbitrary (non-builtin) string id addresses a **custom** message, and its payload is unchecked — the escape hatch for your own message protocol:

```ts
msg.post("#logic", "spawn_wave", { count: 3, boss: true }); // custom id — payload unchecked
```

Passing the id as an already-hashed `Hash` also skips the check, since the hashed form has lost the literal the narrowing needs.

#### Receiving messages with type narrowing

`on_message` delivers `message_id` as a `Hash` (Defold pre-hashes it) and `message` as an untyped record. Because the id arrives already hashed, the string literal a discriminated union would switch on is gone — TypeScript cannot automatically narrow `message` from a runtime `Hash` comparison. The `isMessage` type guard re-introduces the literal at the use site and narrows the payload to its `BuiltinMessages` shape:

```ts
export default defineScript({
  on_message(self, message_id, message) {
    if (isMessage(message_id, message, "contact_point_response")) {
      // message: { position: Vector3; normal: Vector3; distance: number;
      //            other_group: Hash; own_group: Hash; ... } — no cast.
      if (message.other_group == hash("ground")) {
        go.set_position(go.get_position().add(message.normal.mul(message.distance)));
      }
    }
  },
});
```

`isMessage` is the receive-side mirror of `msg.post`'s send-side narrowing: `msg.post(receiver, "contact_point_response", payload)` checks the payload against `BuiltinMessages["contact_point_response"]`, and `isMessage(message_id, message, "contact_point_response")` narrows a received `message` to the same shape. It is a global — no import — and an unknown message id (`isMessage(message_id, message, "not_a_message")`) is a compile error.

The guard ships only as a type declaration; the transpiler lowers the call to its runtime form `message_id == hash("contact_point_response")`, so the types package emits no runtime Lua.

#### Routing many messages with `onMessage`

When a script handles several built-in messages, a chain of `if (isMessage(...))` blocks gets noisy. `onMessage` is a discriminated-union dispatcher built on the same narrowing: each handler key is a built-in message id, and that handler's `message` param is narrowed to the matching `BuiltinMessages` payload. It returns an `on_message` handler, so it slots straight into `defineScript`:

```ts
export default defineScript<Self>({
  on_message: onMessage<Self>({
    contact_point_response(self, message) {
      // message: { normal: Vector3; distance: number; other_group: Hash; ... }
      go.set_position(go.get_position().add(message.normal.mul(message.distance)));
    },
    set_parent(self, message) {
      // message: { parent_id?: Hash; keep_world_transform?: 0 | 1 }
    },
  }),
});
```

`self` threads via the explicit `onMessage<Self>` type argument, mirroring `defineScript<Self>`; a bare `onMessage({...})` defaults it to an empty record. An unknown key is a compile error, just like `isMessage`.

Like `isMessage` and `defineScript`, the dispatcher is declaration-only — the transpiler lowers it to the flat `function on_message(self, message_id, message, sender)` chunk with a `message_id == hash("...")` if/elseif chain, so no `onMessage` symbol or runtime Lua reaches the output.

#### See also

- [Script lifecycle](./script-lifecycle.md) — the `on_message` lifecycle callback and the other typed script hooks.
- [TypeScript gotchas](./typescript-gotchas.md) — why a raw `on_message` handler's `message` is an untyped record, and the cast you would otherwise reach for.

### Where script state lives

A Defold game is many script *instances* sharing a few script *modules*. Where you put a piece of mutable state decides who can see it and change it — one component, every component of one script, every script in the game, or the whole Lua VM. This page walks those four tiers from narrowest to widest, each grounded in the Lua the toolchain actually emits.

This page is about *placement*. The typing model for `self` — how `init` infers it and how `properties` seed it — lives in [Script lifecycle](./script-lifecycle.md).

#### Per-instance state: `self`

State that each component instance owns belongs on `self`. `init`'s returned object is copied onto `self` for *that* component instance, so two game objects running the same script keep independent values: decrement one object's `self.health` and the other's is untouched.

```ts
import { defineScript } from "@defold-typescript/types";

export default defineScript({
  init() {
    return { health: 100 };
  },
  update(self) {
    self.health -= 1;
  },
});
```

Every object that mounts this script gets its own `self.health`. This is the default home for anything an instance must own a private copy of. The full typing model is in [Script lifecycle](./script-lifecycle.md).

#### Sharing state across instances of one script

A module-level `let` or `const` is **not** per-instance. Defold loads each script module once via `require` and caches the result, so a variable declared at module scope is created once and seen by every component instance of that script. The build makes the split visible — `spawnCount` is a module local, while `health` is written onto each instance's `self`:

```ts
import { defineScript } from "@defold-typescript/types";

// Module-level: one value, not per-instance.
let spawnCount = 0;

export default defineScript({
  init() {
    return { health: 100 };
  },
  update(self) {
    self.health -= 1;
    spawnCount += 1;
  },
});
```

```lua
local spawnCount = 0
function init(self)
    -- self.health is set per instance
end
function update(____self)
    ____self.health = ____self.health - 1
    spawnCount = spawnCount + 1
end
```

`spawnCount` is a single Lua **module local** evaluated once at chunk scope; because the module is cached, that one value is **shared by every component instance** that runs this script. Reach for a module local only for constants or a deliberately-shared counter — keep anything each instance must own its own copy of on `self`.

#### Sharing state across different scripts: a module singleton

To share state across *different* scripts — a spawn registry, a score table, an event bus — put it in its own module and import it wherever you need it. Because every `import` lowers to a cached `require`, each script that imports the module sees the same table:

```ts
// registry.ts — one module, shared by every importer.
let spawned = 0;
const names: string[] = [];

export function register(name: string): void {
  spawned += 1;
  names.push(name);
}

export function spawnedCount(): number {
  return spawned;
}
```

```ts
// spawner.ts and hud.ts both import it and see the same state.
import { register, spawnedCount } from "./registry";
```

`import { register } from "./registry"` lowers to a `require` that Defold caches once, so `spawner.ts` and `hud.ts` read and write the **same** `spawned`/`names` values. This is the idiomatic pattern for game-wide tracking — prefer it over raw globals: a module singleton is scoped, typed, and explicit about who depends on it.

#### Truly global variables: `declare global`

The widest tier is a bare Lua global, shared across the entire VM — every script, no import. You reach it from TypeScript with `declare global`. The declaration itself emits no Lua; the first assignment creates the global at runtime:

```ts
declare global {
  var FOO: number;
}
export function bump(): number {
  FOO = FOO + 1;
  return FOO;
}
```

```lua
local ____exports = {}
function ____exports.bump()
    FOO = FOO + 1
    return FOO
end
return ____exports
```

Note what is **not** there: no `local FOO`, no initializer, no `____exports.` prefix. `FOO` is a raw Lua global — broader than a cached module local, because it is scoped to no module at all. TypeScriptToLua emits nothing for the `declare global` block itself; it only tells the type-checker the global exists, and the first assignment creates it VM-wide. Reach for this only for genuine engine or Lua globals you cannot type any other way; for app state, prefer a module singleton.

#### Choosing where state lives

| You want state… | Put it… |
| --- | --- |
| owned by one component instance | on `self` |
| shared by every instance of one script | a module-level `let`/`const` |
| shared across different scripts (app state) | a module singleton (import a shared module) |
| visible to the whole Lua VM, no import | `declare global` — real Lua/Defold globals only |

A rule of thumb: `self` for per-instance state; a module singleton for deliberately-shared app state; `msg.post` or a dedicated manager object when ownership and lifecycle matter; `declare global` only for real Lua/Defold globals. One hot-reload caveat: module state — module locals and singletons alike — persists across `on_reload`, because the cached module is not re-`require`d; only `self` is rebuilt.

#### See also

- [Script lifecycle](./script-lifecycle.md) — typing `self`, `on_message`, and `on_input` with `defineScript`.
- [TypeScript vs Lua](./typescript-vs-lua.md) — the `require`/`import` mapping and the `declare global` lowering this page builds on.
- [Agent runbooks](./agent-runbooks.md#where-script-state-lives) — the condensed self-vs-module-local procedure.

### Vector math

Defold exposes vector arithmetic through Lua metamethods on `vector3`, `vector4`, `quaternion`, and `matrix4`. In TypeScript the same operations are typed as **methods**, not operators: `a.add(b)` instead of `a + b`. The TypeScript-to-Lua transpiler turns these calls into the underlying metamethod invocations at build time, so the runtime cost is identical.

#### Vector3

```ts
const a: Vector3 = vmath.vector3(1, 2, 3);
const b: Vector3 = vmath.vector3(4, 5, 6);

const sum: Vector3 = a.add(b);       // a + b
const diff: Vector3 = a.sub(b);      // a - b
const scaled: Vector3 = a.mul(2);    // a * 2 (scalar)
const halved: Vector3 = a.div(2);    // a / 2 (scalar)
const negated: Vector3 = a.unm();    // unary minus — see the gotchas page
```

`mul` and `div` take a scalar `number`, not another `Vector3`. Component-wise multiplication is not built in; do it explicitly with `vmath.vector3(a.x * b.x, a.y * b.y, a.z * b.z)`.

#### Vector4

The same shape as `Vector3`, with an extra `w` component:

```ts
const v: Vector4 = vmath.vector4(0, 0, 0, 1);
const w: Vector4 = vmath.vector4(1, 0, 0, 0);
const sum: Vector4 = v.add(w);
```

#### Quaternion

`Quaternion.mul` composes two quaternions:

```ts
const q1: Quaternion = vmath.quat_axis_angle(vmath.vector3(0, 1, 0), Math.PI / 2);
const q2: Quaternion = vmath.quat_axis_angle(vmath.vector3(1, 0, 0), Math.PI / 4);
const composed: Quaternion = q1.mul(q2);
```

#### Matrix4

`Matrix4.mul` is overloaded: matrix × matrix returns `Matrix4`, matrix × `Vector4` returns `Vector4`. Matrix × `Vector3` is intentionally a type error — promote the vector to `Vector4` first.

```ts
const m: Matrix4 = vmath.matrix4_translation(vmath.vector3(1, 0, 0));
const m2: Matrix4 = m.mul(m);
const transformed: Vector4 = m.mul(vmath.vector4(0, 0, 0, 1));
```

#### A worked example: the platformer

The eight engine types (`Vector3`, `Hash`, `Url`, `Quaternion`, `Matrix4`, `Vector`, `Vector4`, `Opaque<…>`) are **ambient globals — no import needed**, mirroring the namespace ergonomics (`vmath`, `go`, `sprite`, …). The committed [`docs/examples/platformer/src/player.ts`](https://github.com/defold-typescript/toolchain/blob/main/docs/examples/platformer/src/player.ts) puts the whole pattern on one screen: the `fixed_update` body uses the chained method form for whole-vector arithmetic, plain `+`/`*` on `number` fields for component access, and a `vmath.project` namespace function that returns a scalar with a method-form argument. The last line comes from the `handle_obstacle_contact` collision helper, not the per-frame loop, so the three snippets do not all share one function body.

```ts
// docs/examples/platformer/src/player.ts — `fixed_update(self, dt)`
self.velocity.x = self.velocity.x + accel * self.input_direction * dt; // component access: plain TS arithmetic on number
self.velocity.y = self.velocity.y + gravity * dt;

const pos = go.get_position().add(self.velocity.mul(dt)).add(self.adj);
go.set_position(pos);

const proj = vmath.project(self.correction, normal.mul(distance));
```

Whole-vector operations read left-to-right as a chain of `Vector3` methods (`go.get_position().add(self.velocity.mul(dt))`); per-component reads and writes (`self.velocity.x = self.velocity.x + accel * …`) stay plain TS because each component is a `number`.

#### Why not `v3 + v3`?

TypeScript's binary `+`, `-`, `*`, `/` operators require both operands to be `number` (or `+` accepts `string`). The type-checker rejects `v3a + v3b` with TS2362/TS2365 because `Vector3` is not assignable to either, so writing the operator form fails to compile and you cannot ship code that would crash at runtime.

There is **one** exception: **unary minus**. TypeScript does not flag `-v3a`; it silently produces `number`. This is a TS-level gap the toolchain cannot close with types alone. The typed alternative is `v.unm()`. See [unary minus on Vector3 silently produces number](./typescript-gotchas.md#unary-minus-on-vector3--vector4-silently-produces-number) on the gotchas page for the full story.

### Init

`init` scaffolds a Defold project with a TypeScript surface — or adds TypeScript
to an existing Defold project. It writes the files and stops; run `bun install`
afterward (it prints the reminder).

```sh
bunx @defold-typescript/cli@latest init my-game   # new project in ./my-game
bunx @defold-typescript/cli@latest init .         # scaffold / add to the current folder
```

Use the `@latest` tag when you scaffold: `bunx` caches binaries, and `init` is
what writes your `@defold-typescript/types` version pin, so a stale cache would
pin an older release.

#### A destination is required

`init` takes an explicit destination — there is no implicit "current folder"
default, so it never scaffolds where you did not mean to. Pass a path to create
(or add to) that folder, or `.` to target the folder you are already in. The same
rule applies to [`init-agents`](./agent-runbooks.md#install-the-agent-contract).

#### Two modes

`init` detects whether the destination already holds a `game.project`:

- **New project.** In an empty or non-Defold folder it synthesizes a full Defold
  project (`game.project`, `main/main.collection`, `input/game.input_binding`)
  alongside the TypeScript surface (`src/main.ts`, `tsconfig.json`,
  `package.json`, `.gitignore`, `biome.json`, `mise.toml`, `.vscode/`) and the
  agent contract (`AGENTS.md`, `CLAUDE.md`).
  `game.project` boots the collection and points `[input]` at the binding, so a
  fresh scaffold loads in Defold with no missing references. If the target folder
  already holds both a `.collection` and a `.ts` file (a `--force` synthesis into
  a directory you have authored), the starter `main/main.collection` and
  `src/main.ts` are skipped so your entry files are never clobbered.
- **Add TypeScript.** Run inside a folder that already has a `game.project` and
  `init` adds only the TypeScript infrastructure, leaving `.script`,
  `.collection`, `.gui_script`, `.render_script`, `game.project`, and other engine
  assets untouched. It writes a starter `src/main.ts` only for a fresh scaffold
  shape, never dropping one into a project you have already authored. See
  [Add TypeScript to an existing project](./getting-started.md#add-typescript-to-an-existing-project).

Both modes also write the agent contract — `AGENTS.md` (a managed block delimited
by HTML-comment markers) and `CLAUDE.md` (`@AGENTS.md`) — **when it is absent**. A
plain re-init leaves a contract you already have untouched; re-syncing the managed
block after an upgrade is the `--force` path (see the flag below). Content you add
above or below the markers always survives. This is the same contract the
standalone [`init-agents`](./agent-runbooks.md#install-the-agent-contract) verb
writes.

Scaffolded config files (`tsconfig.json`, `biome.json`, `.vscode/`, `mise.toml`)
merge additively into anything you already have, so re-running `init` refreshes the
managed blocks without disturbing your own entries. For `tsconfig.json` that means
an existing `compilerOptions.typeRoots`, `types`, and `include` survive — including
the `.defold-types` root and pinned engine surface that
[`resolve`](./resolve.md) writes — while the `@defold-typescript/tstl-plugin`
language-service plugin is unioned in exactly once.

#### Flags

- `--template <name>` — pick a starter template when **creating a new project**
  (see below). Rejected in add-TypeScript mode, where there is nothing to
  synthesize.
- `--force` — refresh managed files: repin the managed `@defold-typescript/types`
  and `@defold-typescript/cli` dependencies to the CLI's own version, migrate a
  deprecated Biome `recommended` key, and re-sync the managed `AGENTS.md` block on a
  project that already has one, leaving your other settings in place. This is the
  deliberate upgrade path.
- `--suppress-install-reminder` — silence the `Next: run <pm> install` line when
  you install through your own tooling.
- `--json` — emit the result envelope. See
  [Agent runbooks](./agent-runbooks.md#machine-readable-output).

#### Starter templates

Pick a template with `--template <name>` when creating a new project:

```sh
bunx @defold-typescript/cli@latest init my-game --template minimal
```

- **`default`** — the opinionated layout you get when you omit `--template`: a
  `game.project`, a `main/main.collection`, and a `src/main.ts` whose `init`
  returns a small `vmath.vector3` example state.
- **`minimal`** — the same project layout with an empty-state `src/main.ts` (a
  `defineScript` whose `init` returns `{}`), for starting from a blank script.

Both templates differ only in the synthesized entry script; the shared TypeScript
surface (`tsconfig.json`, `package.json`, `.gitignore`, `biome.json`, `mise.toml`,
and the `.vscode/` files) is identical.

Omitting `--template` is equivalent to `--template default`. An unknown name fails
fast and lists the valid templates:

```
defold-typescript init: unknown template "foo". Valid templates: default, minimal.
```

### Watch

`watch` rebuilds your Lua incrementally on every TypeScript change. Run it in the
editor's integrated terminal and leave it running while you work; the
[Defold editor](./defold-editor.md) picks up each rebuild.

```sh
bunx @defold-typescript/cli watch
```

#### What it does

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

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

#### Keeping the extension surface current

`watch` re-runs [`resolve`](./resolve.md) whenever you save `game.project`,
re-materializing `.defold-types/extensions/` from the declared `[dependencies]`.
It does **not** bootstrap that surface: run `resolve` once before `watch` so the
initial extension types exist; `watch` only reconciles later `[dependencies]`
edits.

#### Flags

- `--json` — stream the build lifecycle as newline-delimited JSON for agents and
  scripts. See [Agent runbooks](./agent-runbooks.md#machine-readable-output)
  for the event stream.

#### As a mise task

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

### Build

`build` transpiles every TypeScript file under `src/` to Lua and writes the result
into the Defold project tree — a one-shot compile. For the incremental loop you
run while editing, see [`watch`](./watch.md).

```sh
bunx @defold-typescript/cli build
```

#### What it does

Each source becomes exactly one output. A file with an
`export default defineScript({...})` (or `defineGuiScript`/`defineRenderScript`)
lifecycle factory becomes a Defold script component
(`src/main.ts` -> `src/main.ts.script`); a plain module with no factory becomes a
Lua module (`src/util.ts` -> `src/util.lua`) — a generated artifact you never edit
or reference by hand, only ever the `src/util.ts` you author. Your `import`
becomes a Lua `require` that resolves against that emitted module, so a shared
module must be built before the script importing it will run. Open the project in
the [Defold editor](./defold-editor.md) (or run it headlessly, below) to play it.

When a source uses a runtime helper TypeScript-to-Lua provides (`Object.keys`,
object spread, and similar), the build also writes a `lualib_bundle.lua` at the
output root automatically; the generated Lua's `require("lualib_bundle")` resolves
against it.

Because the output kind is the factory a source calls, adding or removing a
factory switches the artifact (`src/main.lua` becomes `src/main.ts.script`, or the
reverse). `build` and [`watch`](./watch.md) prune the stale alternative for you, so
a kind switch never leaves the previous output behind. Every generated file
carries a trailing `--# defold-typescript:generated` marker; on a full build the
tool **warns, never deletes** about any marked `.lua` or `.ts.*` output whose
TypeScript source no longer exists, so a deleted or renamed source's orphaned Lua
surfaces for you to remove (the warning names the file and the source to restore).
Hand-authored Lua, which lacks the marker, is never flagged or touched.

A full build also warns when a `.go`/`.collection` `component:` references a mesh
source asset (`.gltf`/`.glb`/`.dae`) directly. Those are imported *into* a
`.model` component, not added as components — the editor rejects the direct form,
but Bob's headless build accepts it and the game object fails at runtime. The
warning names the scene file and the offending path; wrap the mesh in a `.model`
(with a `materials` block) and point the component at the `.model`.

`build` never narrows the API surface — it builds against whatever entrypoint your
`tsconfig` names, the full `@defold-typescript/types` by default. Opt into
per-directory narrowing with [`wall`](./wall.md).

The everyday commands carry no version tag: inside an installed project `bunx`
resolves the `@defold-typescript/cli` that `init` pinned, so the build runs the
version locked alongside your `@defold-typescript/types`. Reserve `@latest` for
`init` and the deliberate upgrade path (see [code editor setup](./editor-setup.md)).

#### Flags

- `--json` — emit the build result as a single JSON object (including the
  `warnings` array) for agents and scripts. See
  [Agent runbooks](./agent-runbooks.md#machine-readable-output).

#### Headless builds (no editor)

`build` transpiles TypeScript to Lua; to compile and run the Defold project itself
from the command line — no editor — drive Defold's headless build tool (`bob`)
through the `defold` subcommand:

```sh
bunx @defold-typescript/cli defold resolve   # fetch library dependencies
bunx @defold-typescript/cli defold build     # debug build into build/default
bunx @defold-typescript/cli defold bundle    # bundle a platform target
```

The first run downloads a version-matched `bob.jar` into a cache dir
(`$DEFOLD_TYPESCRIPT_CACHE/bob` when set, otherwise
`$XDG_CACHE_HOME/defold-typescript/bob`, falling back to
`~/.cache/defold-typescript/bob`) and reuses it afterward. `bob` needs a JVM. It
resolves one in order: the `--java <path>` flag (or `DEFOLD_JAVA`), then `java`
on your `PATH`, then the JDK bundled inside an installed Defold editor. If none
resolve, the command errors and names all three. Native-extension projects can
pass `--build-server <url>`. `bob`'s exit code
propagates, so a failed build fails the command.

Like the engine launcher, the `bob` version tracks the latest stable Defold
release. A project pinned to an older Defold version is a known limitation.

### Wall

This page covers `wall`, the opt-in command for narrowing the API surface of a
source directory to a single script kind. To *add* a surface for native-extension
namespaces instead of narrowing one, see [`resolve`](./resolve.md).

#### Full surface by default

Defold scopes two namespaces to a script kind: `gui.*` resolves only inside a
`.gui_script`, and `render.*` only inside a `.render_script`. Every other
namespace (`go`, `msg`, `vmath`, `sys`, `physics`, …) is available in every kind.

By default `defold-typescript` gives you the **full** `@defold-typescript/types`
surface everywhere. `init`, `build`, and `watch` never change this: they scaffold
and build against whatever entrypoint your `tsconfig` names and never add, remove,
or prune a wall. The full surface never rejects a call the engine would allow, but
it also can't catch a `gui.*` use in a plain `.script`. To get the engine's wall
at compile time, opt in with `wall`.

#### What a wall is

A wall is a composite `tsconfig.json` written into a single-kind source directory
that narrows `compilerOptions.types` to that kind's subpath:

| Script kind      | `types` entrypoint                       | Namespaces           |
| ---------------- | ---------------------------------------- | -------------------- |
| `.script`        | `@defold-typescript/types/script`        | universal only       |
| `.gui_script`    | `@defold-typescript/types/gui-script`    | universal + `gui`    |
| `.render_script` | `@defold-typescript/types/render-script` | universal + `render` |

The root `tsconfig.json` references each walled directory and excludes it from the
root program, so `tsc -b --noEmit` builds every walled directory against only its
narrowed surface — a `render.*` use inside a gui-walled directory becomes a compile
error, while the rest of the project stays full-surface.

A directory is **eligible** to be walled only when every `.ts` source in it is one
kind; a directory mixing kinds cannot be walled, because no single narrowing
applies. `build` and `watch` never touch walls — they are entirely yours to
manage.

#### Interactive

Run `wall` with no arguments in a terminal:

```sh
bunx @defold-typescript/cli wall
```

You get a checkbox of every eligible source directory, pre-checked to the
directories already walled. Checking an unwalled directory walls it; unchecking a
walled directory removes its wall. Mixed-kind directories appear disabled, with
their competing kinds shown as the reason. The final selection **is** the desired
wall set — the command reconciles the project on disk to exactly what you checked.

#### Flags

For agents, CI, and scripted use, pass directories explicitly (a bare `wall` with
no TTY errors rather than hanging on an unrenderable prompt):

```sh
# Wall these directories (added to any already walled)
bunx @defold-typescript/cli wall src/ui src/rendering

# Remove a wall
bunx @defold-typescript/cli wall --remove src/ui

# List current and eligible walls (writes nothing)
bunx @defold-typescript/cli wall --list
bunx @defold-typescript/cli wall --list --json
```

`--json` emits the resulting `directoryWalls` (and, for `--list`, the `eligible`
set) for machine consumption. `--json` is machine-driven intent, so a bare
`wall --json` never opens the interactive menu — pass directories or `--list`.

#### Import the factory from the kind subpath

A wall only holds if a walled source imports its lifecycle factory from the **kind
subpath**, not the main entry:

```ts
// src/ui/hud.ts — inside a gui wall
import { defineGuiScript } from "@defold-typescript/types/gui-script"; // correct
```

Importing the same factory from the main `@defold-typescript/types` entry pulls
*every* `declare global` namespace (including `render`) into the wall's program and
silently defeats the narrowing — `render.*` would type-check inside a gui wall:

```ts
// Wrong: re-introduces the full surface, defeating the wall
import { defineGuiScript } from "@defold-typescript/types";
```

The interactive snippets scaffolded by `init` already import from the kind
subpaths. `build` enforces this: a walled source that imports a lifecycle factory
from the main entry fails the build before transpile, naming the file and the kind
subpath it should import from instead. (`watch` does not enforce it yet — its
session path is a separate slice.)

### Resolve

`resolve` reads the Defold dependencies declared in your `game.project`, fetches
each archive, and generates the TypeScript types for them — so extension
functions and vendored-library modules gain autocomplete and `tsc` coverage with
no hand-written declarations. For what native extensions are and how to declare
them, see [Native extensions](./extensions.md).

```sh
bunx @defold-typescript/cli resolve        # defaults to the current directory
bunx @defold-typescript/cli resolve path/to/project
```

It reads every `dependencies#N` URL under `[project]` in `game.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 `0`.

#### Dependency kinds

`resolve` inspects each declared archive and sorts it into one of three kinds:

| Kind | Detected by | What `resolve` produces |
| ---- | ----------- | ----------------------- |
| **Native extension** | the archive carries one or more `.script_api` docs | one ambient namespace per doc in `.defold-types/extensions/`, plus `"extensions"` on the tsconfig `types` list |
| **Vendored pure-Lua library** | the repo name matches the `@defold-typescript/library-types` corpus, confirmed against the archive | the committed `.d.ts` materialized into `.defold-types/libraries/`, plus `"libraries"` on the tsconfig `types` list |
| **Asset-only / content** | no `.script_api` and no library match — fonts, asset packs, other content archives | nothing: reported and skipped |

A skipped **asset-only** archive is never a failure — `resolve` still exits `0`
and materializes types for the dependencies that do carry them. A typical run:

```
  iap <- https://github.com/defold/extension-iap/archive/main.zip (1 .script_api, download)
  dicebag.dicebag <- https://github.com/paulomrpp/dicebag/archive/main.zip (vendored library)
  <other.url>: asset-only, skipped
defold-typescript resolve: wrote .defold-types/extensions
```

#### The generated surface

For each native extension, `resolve`:

1. downloads and caches the archive (later runs are offline),
2. locates every `.script_api` doc inside it,
3. emits one ambient namespace per doc into `.defold-types/extensions/<namespace>.d.ts`,
4. writes an index barrel and a `package.json` for that sibling surface, and
5. additively appends `"extensions"` to `tsconfig.json` `compilerOptions.types`, so
   it coexists with the pinned engine surface (and the `"libraries"` surface,
   below) under one `typeRoots`.

`.defold-types/` is generated output and is gitignored. Re-run `resolve` whenever
you change `[dependencies]`; each surface reconciles to exactly what is declared
now, so removing a dependency prunes its generated types and drops the tsconfig
entry — nothing stale is left behind.

#### Vendored library types

Many popular Defold libraries are plain Lua — installed via **Fetch Libraries**,
carrying no `.script_api`. This toolchain ships hand-vendored TypeScript types for
a curated set of them in `@defold-typescript/library-types`. When a declared
dependency matches one, its committed `.d.ts` is materialized verbatim (never
regenerated), and the import specifier is the Lua `require` path —
`import * as dicebag from 'dicebag.dicebag'` — so it matches what Fetch Libraries
installs at runtime.

The match keys on the library's **source identity (the repository name)**, not
exact URL equality, so a fork or a pinned-tag archive URL still resolves. Because
a repo name alone can collide — a different library sharing the name, or a fork
that renamed its module folder — the match is then **verified against the
downloaded archive**: `resolve` reads the archive's `.lua` require paths and
materializes only the modules it actually ships. A repo-name match the archive
does not confirm is reported **unverified** (a `stderr` warning) and never
materialized, so a collision cannot inject the wrong types. A declared library
whose vendored `.d.ts` is missing from the shipped corpus is likewise warned and
skipped rather than failing the run.

#### Keeping types in sync with `watch`

A running [`watch`](./watch.md) re-resolves on every `game.project` save, so
editing `[dependencies]` while `watch` is up refreshes `.defold-types/` with no
extra command. `watch` only reconciles on save — it does not bootstrap the
surface — so run `resolve` once first to materialize the initial types.

#### Flags

- `--frozen` — treat the committed pin set as a lockfile: exit non-zero on drift
  (so CI gates the upgrade) and write nothing. See [Pinning extension versions](#pinning-extension-versions).
- `--json` — emit one machine-readable object per run. See
  [Agent runbooks](./agent-runbooks.md#machine-readable-output) for the shape
  (`materializedSurface`; per extension `namespaces`, `provenance`,
  `resolvedVersion`, `pinnedVersion`, `pinStatus`; and a `libraries` array with
  each match's `source`, `modules`, `provenance`, and `verified`).

#### Pinning extension versions

A `dependencies#N` URL is often a **moving** ref (`.../archive/master.zip`) — the
same URL can yield different bytes over time. So the reproducible identity of
*what was actually resolved* is the **sha256 digest of the resolved archive
bytes**, not a URL segment. `resolve` records that digest as the dependency's
version and seeds it into the project's `package.json` when absent, never
clobbering an existing pin:

```jsonc
"defold-typescript": {
  "extensions": {
    "https://github.com/defold/extension-iap/archive/main.zip": "sha256:ab12…"
  }
}
```

A committed pin is human-owned intent. When the URL later yields different bytes,
the fresh digest no longer matches the pin and `resolve` reports **drift**, gated
by two knobs:

- **Default (no flag)** — warns on drift, writing one `stderr` line per drifted
  URL (e.g. `pin drift for https://...: sha256:pinned -> sha256:fresh`) but exits
  `0`, so drift surfaces on a developer's machine without breaking scripted runs.
  Absent pins are seeded; existing pins are never clobbered.
- **`--frozen`** — treats the pin set as a lockfile: exits non-zero on drift and
  writes nothing (no seeding, no clobbering). An unpinned extension passes and
  stays unseeded.

Either way `resolve` still materializes the surface for the drifted dependencies;
only the `package.json` write and the exit code are gated. `--json` reports
`pinStatus` per extension (`unpinned` / `match` / `drift`).

#### Cache location

Downloaded archives are cached so repeated runs stay offline, at
`$XDG_CACHE_HOME/defold-typescript/extensions` (default
`~/.cache/defold-typescript/extensions`). Set `DEFOLD_TYPESCRIPT_CACHE` to
override the root; archives then land under `$DEFOLD_TYPESCRIPT_CACHE/extensions`.

### Live transpile diagnostics

`bunx @defold-typescript/cli@latest init .` scaffolds a TypeScript language-service plugin, `@defold-typescript/tstl-plugin`, into the generated `tsconfig.json`:

```jsonc
{
  "compilerOptions": {
    "types": ["@defold-typescript/types"],
    "plugins": [{ "name": "@defold-typescript/tstl-plugin" }]
  }
}
```

The plugin is added as a managed devDependency at the same time, pinned in lockstep with the other `@defold-typescript/*` packages, so it resolves from your project's `node_modules` once you run `bun install`.

#### What it surfaces

The plugin runs the **same TypeScript-to-Lua diagnostic pass the `build` command uses** against the program your editor already has open, and reports anything the transpiler cannot lower — directly on the offending source span. You see the squiggle in the editor as you type, instead of discovering the failure when you run `build`. Because editor and build share one diagnostic source, they cannot disagree about what is unsupported.

#### It is advisory, not blocking

Every diagnostic the plugin appends carries the `Suggestion` category, never `Error`. It adds editor signal; it never turns valid code red. In particular it **never blocks `tsc --noEmit`** — a project that type-checks clean stays clean in CI even with the plugin active. The plugin is an editor convenience layer; the build path remains the source of truth for what compiles.

#### How it relates to the gotchas guide

This plugin catches constructs the *transpiler* rejects. It does not catch the runtime-semantics traps where valid TypeScript compiles but behaves unexpectedly under Lua — truthiness, `typeof` on engine values, `nil` collapsing, and the rest. Those live in [TypeScript gotchas](./typescript-gotchas.md). The two complement each other: the plugin flags what will not transpile, the gotchas page explains what transpiles but surprises you.

#### Build-time diagnostics in the editor

`init` also scaffolds a `.vscode/tasks.json` carrying two managed tasks — `defold-typescript: build` and `defold-typescript: watch` — that invoke the CLI via `bunx @defold-typescript/cli build` / `… watch`. Run them from the command palette (`Tasks: Run Task`, or `Tasks: Run Build Task` for the build task), and a shared `problemMatcher` routes any `build` failure into VS Code's Problems panel.

This is the build-time complement to the live `tstl-plugin` squiggles above: the plugin flags unsupported constructs as you type, while the task surfaces whatever the actual `build` rejects. No editor extension is required — the matcher is wired entirely in `tasks.json`.

Problems land on the **exact line and column**: each build failure is emitted as a located `  <file>:<line>:<column>: <message>` row, and the matcher captures all four so VS Code anchors the squiggle on the offending span. The `watch` task is a live background watcher — it frames every build cycle with `build started`/`build finished` sentinels, so the Problems panel clears stale entries and re-anchors them on each rebuild. A startup compile error keeps `watch` running: it reports every located error and stays watching, so fixing the file clears the problem in place. The merge is additive — your own tasks are preserved; only the two managed labels are reconciled.

### Debugging TypeScript in Defold

Step through your TypeScript with breakpoints set directly in the `.ts` source, even though Defold runs the transpiled Lua. The toolchain already emits the load-bearing piece: every build writes a `<name>.ts.script.map` source map next to the chunk and appends a `--# sourceMappingURL=` trailer. The [Local Lua Debugger](https://marketplace.visualstudio.com/items?itemName=tomblind.local-lua-debugger-vscode) extension reads that map, so a breakpoint in a `.ts` file resolves to the right generated line with no extra wiring.

#### What `init` scaffolds

Running `bunx @defold-typescript/cli@latest init .` sets up the whole debug path:

- `extensions.json` recommends `tomblind.local-lua-debugger-vscode` — the one required third-party extension for debugging. (Defold Kit is no longer recommended; sumneko Lua is an optional aid for reading generated Lua. See [editor setup](editor-setup.md).)
- `launch.json` adds a `lua-local` configuration named **Defold: Debug (TypeScript)** whose `program.command` is `bun`. It also sets `scriptFiles` (`src/**/*.ts.script`) and `scriptRoots` (`.`, `src`). Local Lua Debugger (>=0.3.0) pre-scans `scriptFiles` for the emitted `--# sourceMappingURL=` trailers to resolve `.ts` breakpoints ahead of time — without it, no source-mapped breakpoint binds — and uses `scriptRoots` to resolve the running Defold chunk path and the map's bare `sources` entry back to files on disk.
- `defold-debug.ts` is a self-contained Bun launcher that downloads and runs a stock `dmengine` (or your native-extension build engine) with its stdio inherited — the pipe Local Lua Debugger attaches over.

The launcher is **Bun, not a shell script**. The upstream `lua-local` template runs a `bash` script and, on Windows, routes it through Git Bash. This toolchain already mandates Bun and targets Windows, so the launcher uses `process.platform` for the OS, `fetch` for the engine download, and `Bun.spawn` for the run — no `bash`, no Git Bash dependency. All `.vscode` debug files merge additively into any config you already have.

#### Automated setup

`init` scaffolds the `.vscode` debug files, but two steps touch your own project files and so are left to a dedicated command:

```
bunx @defold-typescript/cli setup-debug
```

`setup-debug` is idempotent and does three things `init` cannot:

- Adds the `lldebugger` library dependency to `game.project` (at the next free `dependencies#N` index, skipped if already present).
- Writes the ambient `src/lldebugger.debug.d.ts` (the `@noResolution declare module`) alongside the entry-script edit, regenerated whole and skipped when already current.
- Injects the gated `lldebugger.start()` bootstrap into your entry script inside a managed `BEGIN`/`END` block. A re-run refreshes the block if its wording drifted and is otherwise a no-op; a legacy single-marker block from an older version is upgraded in place. The block is kept in exactly one script: any stale managed block in another `src/` script is stripped on each run.

It selects the entry script from the Defold boot path: starting at `game.project`'s `[bootstrap] main_collection`, it walks the referenced `.collection` files (including nested `collection:` references) and collects every `.ts.script` component, mapping each back to its source `.ts`. A single boot-path script is wired automatically; with several, pass `--script <path>` to choose one or run interactively (without `--json`) to pick from a prompt, and `--json` errors naming the candidates. When the boot path reaches no `.ts.script` (or there is no `[bootstrap]`), it falls back to scanning `src/**/*.ts` for a lifecycle-factory call (`defineScript`/`defineGuiScript`/`defineRenderScript`). The plain output names the script added to, any scripts the block was removed from, and the boot-path trace behind the choice; `--json` emits a machine-readable `{command, ok, written, actions, manualSteps, addedTo, removedFrom, bootPath}` result. The same command is available as the `defold-typescript:setup-debug` mise task.

Two steps still require the Defold editor and VS Code and are reported as remaining manual steps:

- Install the *Local Lua Debugger* VS Code extension.
- Run *Project -> Fetch Libraries* so the `lldebugger` module is downloaded.

The manual walkthrough below remains the fallback and documents exactly what `setup-debug` automates.

#### One-time setup

1. **Install the recommended extension.** Open the project in VS Code and accept the *Local Lua Debugger* recommendation (or install `tomblind.local-lua-debugger-vscode` directly).

2. **Add the `lldebugger` library to Defold.** In `game.project`, add the dependency:

   ```
   https://github.com/defold-typescript/toolchain/releases/download/lldebugger-v1/lldebugger.zip
   ```

   This is our vendored, MIT-licensed snapshot of `ts-defold/defold-lldebugger`, hosted from this repo's releases — that is why the URL differs from the upstream docs. Then run *Project -> Fetch Libraries* in the Defold editor so the `lldebugger` Lua module is available to `require`.

3. **Start the debugger from your entry script.** First create an ambient declaration at `src/lldebugger.debug.d.ts` so TypeScript and [TypeScriptToLua](https://typescripttolua.github.io/) (TSTL) both know the module without resolving it:

   ```ts
   /** @noResolution */
   declare module "lldebugger.debug" {
     export function start(): void;
   }
   ```

   Then add the debugger entry near the top of your main script, inside the managed block, gated so it only runs in a debug build:

   ```ts
   // defold-typescript:setup-debug BEGIN — managed block, do not edit
   import * as lldebugger from "lldebugger.debug";

   if (sys.get_engine_info().is_debug) {
     lldebugger.start();
   }

   // defold-typescript:setup-debug END
   ```

   The `@noResolution` ambient declaration must live in a `.d.ts`, not inline in a `.ts` — under `moduleResolution: "Bundler"` an inline `declare module` augmentation that the entry script also imports fails to type-check. With the declaration in the ambient file, TypeScript leaves the module unresolved and [TypeScriptToLua](https://typescripttolua.github.io/) (TSTL) keeps the literal path, so the emitted Lua is `require("lldebugger.debug")` followed by `lldebugger.start()`. The `is_debug` guard keeps the call inert in release builds, so the entry is safe to leave in shipped code — it only activates in a debug build with the debugger attached. `setup-debug` writes both files for you; the `BEGIN`/`END` sentinels let a re-run refresh the block if its wording changes.

#### Launching a debug session

The launcher runs whatever already sits under `build/`; it does **not** compile the Defold project itself. The CLI build loop produces both artifacts headlessly — no editor required:

1. Transpile your TypeScript so the `.ts.script` and `.ts.script.map` files are current (`bunx @defold-typescript/cli build`, or keep `watch` running).
2. Compile the Defold project so `build/default/game.projectc` exists:

   ```sh
   bunx @defold-typescript/cli defold resolve   # first time / after editing dependencies
   bunx @defold-typescript/cli defold build      # debug build into build/default
   ```

   `defold build` runs Defold's headless `bob` tool — see [Build](build.md#headless-builds-no-editor) for the JVM and cache details. Native-extension projects must add `--build-server <url>` so `bob` can compile the engine remotely.
3. In VS Code, select the **Defold: Debug (TypeScript)** launch configuration and start it (F5).
4. The Bun launcher resolves the engine, then runs `build/default/game.projectc`. Set breakpoints in your `.ts` files; they resolve through the emitted `<name>.ts.script.map`.

The launcher prefers the native-extension build engine at `build/<platform>/dmengine` when it exists and otherwise downloads a stock engine from `d.defold.com` next to the launcher (`.vscode/dmengine`). The download is a one-time fetch per platform, and the scaffolded `.gitignore` keeps that binary out of version control.

##### Native-extension runtime libraries

On a build-engine run the launcher checks each supported native extension's declared runtime libraries and warns-and-continues if any are missing — it never fetches them, because no extension has a fetchable source yet. OpenAL on Windows is currently the only declared extension: native-extension builds need `OpenAL32.dll` and `wrap_oal.dll` placed by hand next to the build engine (in `build/x86_64-win32/`). The Defold build server does not ship these runtime DLLs and no Defold-hosted archive serves them, so the launcher cannot fetch them; the copy fix is tracked upstream at [defold/defold#11860](https://github.com/defold/defold/issues/11860). When they are missing on a Windows build-engine run the launcher prints a one-line reminder and continues. macOS and Linux declare no native-extension runtime libraries and resolve OpenAL from the system, so nothing needs placing.

##### Building from the editor instead

The CLI build loop above is the primary path and needs no editor. If you prefer, you can still produce `build/default/game.projectc` (and any native-extension engine) by building from the Defold editor before launching from VS Code — the launcher runs whatever is already under `build/` either way.

#### See also

- [Script lifecycle](script-lifecycle.md) — typing `self` and the lifecycle hooks you will step through.
- [Code editor setup](editor-setup.md) — the rest of the scaffolded `.vscode/` config and the watch loop.

### Agent runbooks

Harness-neutral procedures for driving `defold-typescript` from an automated
agent. `defold-typescript` is a CLI published to npm (run with `bunx`) plus a
types package; it ships no
harness-specific skill or command assets, so the durable interface for an agent
is the CLI verbs themselves and their machine-readable `--json` output. Every
runbook below works from any harness: run the command, read the JSON envelope on
stdout, gate on `ok`.

Each one-shot command (`init`, `build`, `resolve`) prints a single JSON object
when given `--json`. The envelope is always one of two shapes:

```json
{ "command": "<verb>", "ok": true, "written": ["<path>", "..."] }
```

```json
{ "command": "<verb>", "ok": false, "error": "<message>" }
```

The agent branches on `ok`: on `true`, read `written` for the paths the command
created or updated; on `false`, read `error` for the failure reason. Some verbs
add fields to the success envelope (noted per runbook), but `command`, `ok`, and
either `written` or `error` are always present.

#### Machine-readable output

Every command accepts `--json`. The one-shot commands (`init`, `build`,
`setup-debug`, `defold`) print a single JSON object to stdout, terminated by a
newline; [`watch`](./watch.md) streams newline-delimited JSON (one object per
line):

```sh
bunx @defold-typescript/cli build --json
# {"command":"build","ok":true,"written":["src/main.ts.script", "src/util.lua", ...],"warnings":[]}
```

A failure flips `ok` to `false` and carries an `error` string instead of
`written`. On [`build`](./build.md), `warnings` carries the sourceless-orphan
lines and scene-resource-mismatch lines (empty when there are none). Optional fields (`defoldVersion`,
`defoldChannel`, `apiSurface`, `materializedSurface`, …) appear only when they
apply.

`watch` is long-running, so `--json` streams **newline-delimited JSON (NDJSON)** —
one object per line, one line per event. The full lifecycle reads
`start` → `build` → `rebuild`* → `resolve`* → `stop`:

```sh
bunx @defold-typescript/cli watch --json
# {"command":"watch","event":"start","ok":true,"written":[]}
# {"command":"watch","event":"build","ok":true,"written":[...],"warnings":[]}
# {"command":"watch","event":"rebuild","ok":true,"written":[...],"changed":["src/main.ts"],"removed":[]}
# {"command":"watch","event":"rebuild","ok":false,"error":"..."}
# {"command":"watch","event":"resolve","ok":true,"written":[]}
# {"command":"watch","event":"stop","ok":true,"written":[]}
```

A `resolve` event is emitted whenever a `game.project` save re-resolves the
extension surface (re-materializing `.defold-types/extensions/` from the declared
`[dependencies]` URLs). `start` arrives once, before the initial full build — the
process is up and listening. `stop` arrives once on graceful shutdown. A failed
startup (missing `tsconfig.json`, etc.) emits `start` then exits non-zero with
**no** `stop` line; a rebuild that fails emits an `ok: false` line **to stdout
too**, so a line-reader sees one uninterrupted stream — failures never split off
to stderr. Read each line as it arrives and react per event. Without `--json`,
stdout stays the human `wrote N files: …` output and rebuild errors stay on
stderr.

[`resolve --json`](./resolve.md) reports `materializedSurface` (the written
directory, or `null` when nothing was materialized) and, per extension, the `url`,
generated `namespaces`, `scriptApiCount`, `provenance` (`cache` or `download`),
whether it was `assetOnly`, the `resolvedVersion` (sha256 digest of the resolved
archive bytes), — when the project pins that url — the `pinnedVersion`, and the
`pinStatus` (`unpinned` / `match` / `drift`). A separate `libraries` array reports
each asset-only dependency that matched a [vendored
library](./resolve.md#vendored-library-types) — its `url`, `source` (the vendored
source identity), materialized `modules`, `provenance` (`vendored`), and `verified`.
A `verified: false` entry (with an empty `modules`) is a repo-name match the
downloaded archive did not confirm; it is reported but never materialized:

```jsonc
{
  "command": "resolve",
  "ok": true,
  "written": [],
  "materializedSurface": ".defold-types/extensions",
  "extensions": [
    {
      "url": "https://github.com/defold/extension-iap/archive/main.zip",
      "namespaces": ["iap"],
      "scriptApiCount": 1,
      "provenance": "download",
      "assetOnly": false,
      "resolvedVersion": "sha256:ab12…",
      "pinnedVersion": "sha256:ab12…",
      "pinStatus": "match"
    }
  ],
  "libraries": [
    {
      "url": "https://github.com/paulomrpp/dicebag/archive/main.zip",
      "source": "dicebag",
      "modules": ["dicebag.dicebag"],
      "provenance": "vendored",
      "verified": true
    }
  ]
}
```

A `pinnedVersion` field is only present when the project's `package.json` records
a pin for that `url`. See [Resolve](./resolve.md#pinning-extension-versions) for
what `pinStatus` drives.

#### Offline knowledge pack

`@defold-typescript/docs` ships two generated, never-hand-edited files at
`node_modules/@defold-typescript/docs/`:

- `llms.txt` — a curated index (per [llmstxt.org](https://llmstxt.org/)): one
  link per guide page and per API namespace.
- `llms-full.txt` — the whole guide inlined plus a compact
  `namespace.function(signature)` index of the entire API surface.

`llms-full.txt` is self-contained: an agent in a consumer project that has only
`node_modules` and the in-project source can read every mechanic and signature
from this one file — no network, no monorepo checkout. The docs site serves the
same pair at `/llms.txt` and `/llms-full.txt`. Both are regenerated from the
guide and the typed API on every docs build and drift-gated, so they never go
stale against the shipped types.

This pack documents **this toolchain's TypeScript surface**. Defold's own engine
docs are a separate, Lua/C++-first set served at `defold.com/llms-*.txt` — reach
for those (and cross-reference the types) via
[Reach upstream Lua docs and convert](#reach-upstream-lua-docs-and-convert).
Do not confuse the two `llms-full.txt` files: this one is the port; `defold.com`'s
is the engine.

#### Helper and codegen scripts (Bun, `/scripts`)

When a task needs a build tool, a codegen pass, or a one-off maintenance script,
do **not** write it into `src/` and do **not** run it with `node`. Two rules
keep such scripts off the game's Lua build path:

- **Location:** put the script in a project-root `/scripts` folder. The Defold
  build selects source by `tsconfig.include` (default `src/**/*.ts`) and ignores
  `exclude`, so any `.ts` under `src/**` is transpiled to Lua and shipped —
  `/scripts` is outside that include, and outside the Defold-pinned main
  `tsconfig.json`.
- **Runner and typing:** run with `bun scripts/foo.ts` (never `node`); `node:*`
  builtins work under Bun and are typed by `@types/bun`. Add a
  `scripts/tsconfig.json` with `"noEmit": true`, `"types": ["bun"]`, and
  `"include": ["**/*.ts"]` — no Defold pin. Script dependencies go in the root
  `package.json` `devDependencies`.

See the [Helper scripts](./helper-scripts.md) guide for the full rationale and a
copy-pasteable config.

#### Verify against the real API surface

This section governs every runbook below it. Before answering any "how do I…"
question about a Defold symbol, **confirm the symbol against the installed
surface** — that it exists, its namespace, and its exact signature. An agent's
default instinct is wrong here: the Lua-first manuals at defold.com and the
`ts-defold` (`@ts-defold/types`) lore baked into training both describe surfaces
that **diverge** from this toolchain's. Never emit a signature from training,
from `ts-defold`, or from a raw Lua doc without first checking it exists in the
materialized `.defold-types/` surface or the installed `@defold-typescript/types`
package. When recollection and the on-disk surface disagree, the surface wins.

##### Where the truth lives (reachable-surface map)

In a consumer project an agent can read only these; everything else (the
generation pipeline, fixtures, monorepo planning docs) is contributor-only and
absent from an install:

| Location                                                                        | What it holds                                                                                                                            | When it exists                        |
| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `.defold-types/<surfaceId>/*.d.ts`                                              | the pinned ambient engine surface (e.g. `.defold-types/defold-1.12.4/`)                                                                  | after `build`; gitignored but on disk |
| `node_modules/@defold-typescript/types/generated/*.d.ts`                        | namespace signatures (`go`, `vmath`, `factory`, …)                                                                                       | always, once installed                |
| `node_modules/@defold-typescript/types/src/`                                    | the three factories (`lifecycle.ts`) and the narrowing guards (`message-guard.d.ts`, `message-dispatch.d.ts`, `window-event-guard.d.ts`) | always, once installed                |
| `node_modules/@defold-typescript/docs/guide/*.md`                               | this guide, refreshed on every install                                                                                                   | always, once installed                |
| `packages/types/generated`, `packages/types/fixtures`, `packages/types/scripts` | generator inputs and outputs — **contributor-only**                                                                                      | only in a clone of this monorepo      |

The pointers the `init-agents` managed block writes are the layered pack:
`node_modules/@defold-typescript/docs/llms.txt` (the map) and
`node_modules/@defold-typescript/docs/llms-full.txt` (the grep corpus), with the
individual `guide/<page>.md` pages and the typed API in
`@defold-typescript/types/generated/*.d.ts` alongside them.

##### Confirm a signature

Read the signature from the namespace declaration instead of recalling it. Grep
the generated `.d.ts` for the function:

```sh
grep -rn "function create" node_modules/@defold-typescript/types/generated/
```

Quote what the surface declares as authoritative — for `factory.create` it is
`factory.create(url, position?, rotation?, properties?, scale?): Hash`. If the
grep returns nothing, the symbol does not exist on this surface; do not invent
it.

##### Reach upstream Lua docs and convert

Defold's own manuals and API reference are Lua-first. When the mechanic you need
is only documented there, run the conversion loop: **locate the mechanic** in
the Lua docs -> **find its namespace** in the generated `.d.ts` -> **confirm the
signature** as above -> **translate the idioms** to the TypeScript surface.

Defold serves its whole documentation set as agent-ready text — reach for these
to **locate the mechanic**, never to copy a call signature:

- `https://defold.com/llms-full.txt` — manuals, API reference, and examples combined.
- `https://defold.com/llms-apis.txt` — the C++/Lua/extension API reference alone.
- `https://defold.com/llms-manuals.txt` — the conceptual manuals alone.
- `https://defold.com/llms-examples.txt` — worked examples alone.

These describe the engine's **Lua and C++** surface, not this toolchain's
TypeScript one: argument order, optionality, and even whether a symbol exists can
differ, so treat them as a concept-and-mechanic reference only. Once you know
*what* to call, switch to the generated `.d.ts`
([Confirm a signature](#confirm-a-signature)) for the actual TypeScript
signature you author against; when the two disagree, the `.d.ts` wins. A
namespace in the Lua docs can be absent from TypeScript because it is not a
scriptable runtime module at all — Defold has no `input` namespace, for example;
input arrives through the `on_input` hook, not a polling API.

| Lua idiom                         | TypeScript surface                          |
| --------------------------------- | ------------------------------------------- |
| `function init(self) … end`       | `defineScript({ init() { … } })`            |
| `obj:method(a)`                   | `obj.method(a)` (method form)               |
| `local x, y = f()` (multi-return) | `const [x, y] = f()` / `LuaMultiReturn`     |
| `hash("player")`                  | `hash("player")`, or a pre-hashed `Hash` id |
| `msg.post("#comp", "msg", {})`    | `msg.post("#comp", "msg", {})`              |

##### Fetch upstream on demand (gitignored, not a submodule)

When you need the engine's own API data or source, pull it on demand into a
gitignored path — **do not add a `defold/defold` git submodule**. A submodule is
a multi-GB tree pinned to one engine SHA that every clone then carries; the API
data you actually need is the few-hundred-KB `ref-doc.zip` the type generator
already consumes, cached at `~/.cache/defold-typescript/ref-doc/<version>/`
(`DEFOLD_TYPESCRIPT_CACHE` overrides the cache root). Read the cached
`ref-doc.zip` there, or for the rare source-reading case shallow-clone
`defold/defold` into a gitignored dir. This is a cached download, **not a
submodule** — the on-demand fetch keeps the repo small.

##### The verification loop

Once converted, prove it compiles before handing it back: write the snippet, run
`build --json`, and on `ok: false` read the `error` span, fix the source, and
rebuild. This is the same loop as [Fix the Lua output](#fix-the-lua-output); the
[script lifecycle](./script-lifecycle.md) page covers which hooks and which
`self` typing each script kind exposes. On `ok: true` the build envelope adds a
`warnings` array. It lists two kinds of issue, empty when clean, and the build
never fixes either for you:

- **Sourceless outputs** — a generated `.lua`/`.ts.*` left without a TypeScript
  source (a deleted or renamed source), each naming the stale file and the
  source to restore.
- **Scene-resource mismatches** — a `.go`/`.collection` whose `component:`
  points at a mesh source asset (`.gltf`/`.glb`/`.dae`) instead of a `.model`
  component. Bob builds this silently, but the game object fails at runtime, so
  the CLI surfaces at build time what only the editor would otherwise catch.
  Wrap the mesh in a `.model` (with a `materials` block) and point the component
  at the `.model`.

#### Scaffold a project

**Goal:** create a new TypeScript surface — either a fresh project, or the
TypeScript layer added to an existing Defold project.

**Command (fresh project, new folder):**

```sh
bunx @defold-typescript/cli@latest init my-game --json
```

**Command (existing Defold project — run inside the folder that holds
`game.project`):**

```sh
bunx @defold-typescript/cli@latest init . --json
```

`init` requires an explicit destination folder — pass a path to create it, or `.`
for the current folder. There is no implicit current-folder default, so an
invocation with no path fails fast (`ok: false`) rather than scaffolding into the
working directory by accident. `init` then detects whether a `game.project` is
already present at the destination and either scaffolds a whole new project or
adds the TypeScript surface alongside the existing one.

**Returns:**

```json
{
  "command": "init",
  "ok": true,
  "written": ["tsconfig.json", "src/main.ts", "..."],
  "operations": [
    { "target": "tsconfig.json", "status": "merged" },
    { "target": "src/main.ts", "status": "skipped", "detail": "existing project sources present" }
  ]
}
```

On failure:

```json
{ "command": "init", "ok": false, "error": "<message>" }
```

**Reading `ok`:** if `ok` is `true`, the scaffold succeeded and `written` lists
every file created or modified — use it to know what to open next. If `ok` is
`false`, stop and surface `error`; nothing was scaffolded.

**Reading `operations`:** each entry pairs a `target` with a `status` of
`written` (freshly created), `merged` (an existing `tsconfig.json` was preserved
and refreshed in place), or `skipped` (left untouched, with a `detail` reason —
e.g. your own `src/main.ts` or engine sources already present). Branch on
`status` when you need to distinguish a merge from a clobber.

#### Install the agent contract

**Goal:** drop an agent contract at the project root so any harness (or human)
opening the repo finds the conventions and a pointer to the installed guide.

**Command:**

```sh
bunx @defold-typescript/cli@latest init-agents . --json
```

Like `init`, `init-agents` requires an explicit destination — pass a path or `.`
for the current folder; a missing path fails fast (`ok: false`). This writes two files. `AGENTS.md` carries a managed block delimited by HTML
comment markers; `CLAUDE.md` is the single line `@AGENTS.md`, re-exporting it.
Only the content **between** the markers is ever rewritten, so any notes you add
above or below the block survive re-runs untouched. If `AGENTS.md` already exists
without the markers, the block is appended after one blank line and your prior
content is left intact; a `CLAUDE.md` that already equals `@AGENTS.md` is left
byte-for-byte unchanged. The block is versionless — its pointers resolve to
`node_modules/@defold-typescript/docs/llms.txt` and `llms-full.txt`, which the
install swaps under the same paths — so the verb is safe to re-run any time.

[`init`](./init.md) writes the same contract as part of its scaffold: a fresh
project gets `AGENTS.md` + `CLAUDE.md` created, but a plain re-init leaves an
existing contract untouched. Re-syncing the managed block on a project that
already has one is the `--force` path — `init . --force` (or the standalone
`init-agents` verb) refreshes the block after an upgrade.

**Returns:**

```json
{ "command": "init-agents", "ok": true, "written": ["AGENTS.md", "CLAUDE.md"] }
```

On failure:

```json
{ "command": "init-agents", "ok": false, "error": "<message>" }
```

**Reading `ok`:** if `ok` is `true`, `written` lists the files touched in order;
a re-run that changes nothing omits the untouched file. If `ok` is `false`, stop
and surface `error`; nothing was written.

#### Regenerate extension types

**Goal:** refresh the ambient TypeScript surface for native extensions after a
`game.project` `[dependencies]` change, so extension namespaces stay in sync with
the declared archives. This automates the workflow described in
[Typing native extensions](./extensions.md).

**Command (run from the project root, after editing `[dependencies]`):**

```sh
bunx @defold-typescript/cli resolve --json
```

`resolve` reads each declared extension's `.script_api`, regenerates the
gitignored `.defold-types/extensions/` ambient surface, and rewrites its index
and `package.json` to exactly the declared set.

**Returns** the same one-shot envelope keyed `command: "resolve"`, plus an
`extensions` array reporting provenance for each resolved dependency:

```json
{
  "command": "resolve",
  "ok": true,
  "written": [],
  "materializedSurface": ".defold-types/extensions",
  "extensions": [
    {
      "url": "<archive url>",
      "provenance": "<cache | download>",
      "namespaces": ["<namespace>"],
      "scriptApiCount": 1,
      "assetOnly": false,
      "resolvedVersion": "<version>",
      "pinStatus": "<unpinned | match | drift>"
    }
  ]
}
```

On failure:

```json
{ "command": "resolve", "ok": false, "error": "<message>" }
```

**Reading `ok`:** if `ok` is `true`, the extension surface is current —
`materializedSurface` is the regenerated surface directory
(`.defold-types/extensions`), and `extensions` records where each dependency
came from (`provenance`), how many `.script_api` files it contributed
(`scriptApiCount`; an `assetOnly` dependency contributes no types), and its pin
state (`resolvedVersion`/`pinStatus`). The `written` array is always empty for
`resolve`. If `ok` is `false`, surface `error`; the existing surface is left
untouched.

#### Add a script

**Goal:** add a new gameplay script to a TypeScript Defold project and attach it
so it runs. There is no `add` verb — the workflow composes ordinary file
creation with the shipped `build` verb, then a scene-file edit to wire the
compiled component.

**1. Write the source.** One Defold script per file under `src/`, exporting a
single lifecycle factory as `default` (never two in one file). The factory
decides the compiled kind:

| Source factory       | Compiled artifact         | Referenced by                                                  |
| -------------------- | ------------------------- | -------------------------------------------------------------- |
| `defineScript`       | `<name>.ts.script`        | a game object (`.go` / `.collection`) as a component           |
| `defineGuiScript`    | `<name>.ts.gui_script`    | a GUI scene (`.gui`), as its **Script** property               |
| `defineRenderScript` | `<name>.ts.render_script` | the render pipeline (a `.render` file, set via `game.project`) |

A source that calls no factory emits a plain `<name>.lua` module to `import`
instead. Which hooks to export (`init`, `update`, `fixed_update`, `on_message`,
`on_input`, `final`, …) and how `self` is typed are covered in
[Script lifecycle](./script-lifecycle.md).

**2. Build** (from the project root):

```sh
bunx @defold-typescript/cli build --json
```

Or, if a [`watch --json`](#fix-the-lua-output) is already running, just save the
file and read its `rebuild` event instead of invoking `build`.

**Returns** the one-shot envelope keyed `command: "build"`, plus the build
context fields:

```json
{
  "command": "build",
  "ok": true,
  "written": ["src/<name>.ts.script", "..."],
  "defoldVersion": "<version>",
  "defoldChannel": "<stable | beta | alpha>",
  "apiSurface": "<surface id>",
  "materializedSurface": "<path | null>"
}
```

On failure:

```json
{ "command": "build", "ok": false, "error": "<message>" }
```

**Reading `ok`:** if `ok` is `true`, the script transpiled — `written` lists the
emitted artifact (`.ts.script`, `.ts.gui_script`, or `.ts.render_script`) to
attach next; `defoldVersion` and `apiSurface` record which API surface it was
built against; `defoldChannel` records the resolved release channel (`stable`
unless pinned or passed via `--channel`; it does not yet change which surface is
fetched). If `ok` is `false`, the build failed — surface `error` and follow
[Fix the Lua output](#fix-the-lua-output).

**What `build` writes.** Each `.ts` source under `src/` produces exactly one
output in the Defold project tree — a script component or a `<name>.lua` module,
per the table above. `import` is rewritten to `require("<module>")` resolving
against the emitted `.lua`, so a shared module must be built for its require to
resolve at runtime. Two runtime modules are synthesized at the output root on
demand: `lualib_bundle.lua` (when a source uses a TS runtime helper like
`Object.keys` or spread) and `defold_typescript_timers.lua` (when timers are
used).

Who creates these: [TypeScriptToLua](https://typescripttolua.github.io/) (TSTL)
produces the Lua *content* in memory; the CLI writes the *files*, choosing the
`.ts.script` / `.ts.gui_script` / `.ts.render_script` / `.lua` name and location.
TSTL never touches disk — that is why the outputs carry Defold-correct extensions
instead of plain `.lua`. Treat the `--json` `written` array as the authoritative
list of what landed; do not infer paths.

**3. Attach the compiled script.** Building only produces the artifact; nothing
runs until a scene references it as a component. Scene files (`.go`,
`.collection`, `.gui`, `.render`) reference the **compiled** artifact, never the
`.ts` source. A game object references a `.ts.script` through a `components { … }`
entry naming its project-root-absolute path:

```
components {
  id: "player"
  component: "/src/player.ts.script"
}
```

In a standalone `.go` the block appears verbatim. When the game object is
embedded in a `.collection`, Defold stores the same block as an escaped string
inside an `embedded_instances { data: "…" }` entry — the form to write when
editing the file directly. The platformer example shows this in
[`game/player.collection`](https://github.com/defold-typescript/toolchain/blob/main/docs/examples/platformer/game/player.collection):

```
embedded_instances {
  id: "player"
  data: "components {\n"
  "  id: \"player\"\n"
  "  component: \"/src/player.ts.script\"\n"
  ...
  "}\n"
  ...
}
```

A `.ts.gui_script` is referenced by a `.gui` scene's **Script** property and a
`.ts.render_script` by the render pipeline, the same compiled-artifact rule.

**4. Verify the attachment.** Two checks confirm the script is wired in:

- Grep the scene files for the compiled name:

  ```sh
  grep -rl "player.ts.script" --include="*.go" --include="*.collection" --include="*.gui" .
  ```

  A hit means a scene references it; no hit means it is orphaned and will not
  run.

- Defold compiles only **reachable** resources, so after a Defold build
  (the CLI's `defold build` subcommand) an attached script produces `build/default/src/player.ts.scriptc`
  — the path mirrors the source — while an orphaned script never appears under
  `build/default/` at all. (The `_generated_*` artifacts there are inlined or
  asset-derived resources — embedded game objects, components, textures — never
  referenced script files, which keep their source path.)

#### Narrow engine callback payloads

**Goal:** type an engine callback's untyped payload without hand-rolling `typeof`/`in`/`as`.

**Rule for clankers:** when an engine callback hands back an untyped or `unknown`
payload that is discriminated by a *separate* id/event argument, reach for the
**provided declaration-only guard** before reaching for `typeof`/`in`/`as`.
TypeScript cannot correlate two independent parameters, and Defold's ids/event
constants are pre-hashed `Hash` values or branded numbers — neither works as a
discriminated-union tag. Each guard below re-introduces the discriminant at the
use site. They are all **declaration-only**: the transpiler lowers each call to
its runtime comparison, so there is no runtime Lua symbol and **no import to
add**.

`on_message` — narrow one message with `isMessage`, or route many with `onMessage`:

```ts
export default defineScript({
  on_message(self, message_id, message) {
    if (isMessage(message_id, message, "contact_point_response")) {
      // message narrowed to the contact_point_response payload — no cast.
      print(message.distance);
    }
  },
});
```

`window.set_listener` — narrow the callback's `data` with `isWindowEvent`:

```ts
window.set_listener((self, event, data) => {
  if (isWindowEvent(event, data, window.WINDOW_EVENT_RESIZED)) {
    // data narrowed to { width: number; height: number } — no cast.
    print(data.width, data.height);
  }
});
```

An unknown id/event constant is a compile error, so the guard also catches typos.
The full narrowing reference, including `onMessage`'s multi-message dispatcher,
lives in [Typed messages](./messages.md#receiving-messages-with-type-narrowing)
and the [`window.set_listener` gotcha](./typescript-gotchas.md#windowset_listener-hands-event-and-data-as-separate-params).

#### Fix the Lua output

**Goal:** recover from a transpile failure reported by `build` or `watch`.

**Command (re-run after each source fix):**

```sh
bunx @defold-typescript/cli build --json
```

On a transpile failure the one-shot `build --json` envelope carries the message:

```json
{ "command": "build", "ok": false, "error": "<message>" }
```

Under a long-lived `watch --json`, the same failure arrives as an NDJSON event on
stdout (one JSON object per line) keyed `command: "watch"`:

```json
{ "command": "watch", "event": "rebuild", "ok": false, "error": "<message>" }
```

The first build emits `event: "build"`; each later rebuild emits
`event: "rebuild"`. `build` and the transpile-diagnostics pass share one
diagnostic run, so the `error` names the offending source span.

**Reading `ok`:** while `ok` is `false`, read `error` for the failing span,
then fix the source and rebuild. Two pages route the fix:
[TypeScript gotchas](./typescript-gotchas.md) for the runtime-semantics traps
that compile clean but surprise under Lua, and
[Transpile diagnostics](./transpile-diagnostics.md) for what the diagnostic pass
surfaces. Repeat until `ok` is `true`, then read `written` as in
[Add a script](#add-a-script).

#### Drive the engine build

**Goal:** once the TypeScript surface transpiles clean, run the actual Defold
engine build headlessly — resolve native dependencies, compile the project, or
produce a platform bundle — without opening the editor. This is the autonomous
phase *after* the [type](#verify-against-the-real-api-surface) and
[transpile](#fix-the-lua-output) loop: the `.ts` sources are already emitted as
Defold artifacts, and now [bob](https://defold.com/manuals/bob/) (the engine's
command-line builder) turns the project tree into engine output.

**Commands (run from the project root):**

```sh
bunx @defold-typescript/cli defold resolve --json   # fetch native extension deps
bunx @defold-typescript/cli defold build --json     # compile to build/default
bunx @defold-typescript/cli defold bundle --json     # produce a platform bundle
```

Each `defold <sub>` verb shells out to bob and, under `--json`, keeps stdout to
**exactly one JSON object** — bob's own chatter is captured, not streamed, so a
line-reader can `JSON.parse` stdout deterministically. The envelope is:

```json
{ "command": "defold", "subcommand": "build", "ok": true, "exitCode": 0, "output": "<bob tail>" }
```

On a non-zero bob exit:

```json
{ "command": "defold", "subcommand": "build", "ok": false, "exitCode": 17, "error": "bob build exited with code 17", "output": "<bob tail>" }
```

`output` is a trimmed tail of bob's combined stdout/stderr, present for
diagnostics on both outcomes. Without `--json`, bob's output streams live to the
terminal instead and no JSON is written.

**Reading `ok` / `exitCode`:** branch on `ok` first — `true` means bob succeeded
and the CLI's exit code is `0`. On `ok: false`, the CLI exit code **is** bob's
own `exitCode` (not a flat `1`), so a caller can distinguish bob failures by
code; read `output` for the tail of what bob printed and `error` for the summary.

**Preconditions — now satisfied autonomously:** two setup steps that used to
require a human are handled for you. bob needs a Java runtime, and `defold`
resolves one in order (`--java`/`DEFOLD_JAVA` override → `java` on `PATH` → the
installed editor's bundled JDK), so a machine with only the Defold editor
installed builds with no separate JDK. bob itself (`bob.jar`) is auto-downloaded
to the cache on first use and reused thereafter. The one precondition still
required is **network egress**: the first `defold resolve`/`build` fetches
`bob.jar` and any native extension archives, so an air-gapped run fails until the
cache is warmed.

#### Combine components on a game object

**Goal:** put several components — scripts, a sprite, a collision object — on one
game object and let them cooperate.

One `.go` (or an `embedded_instances` block inside a `.collection`) lists each
component under its own `id`. A script reaches a *sibling* component on the same
object by that `#`-prefixed id — no path is needed because they share the object.
The platformer's [`game/player.collection`](https://github.com/defold-typescript/toolchain/blob/main/docs/examples/platformer/game/player.collection)
embeds the player script next to its sprite and collision object exactly this
way; the [Add a script](#add-a-script) runbook shows the `embedded_instances`
form to write when editing the scene file directly.

```ts
import { defineScript } from "@defold-typescript/types";

export default defineScript({
  on_input(self, action_id) {
    if (action_id == hash("jump")) {
      // "#" addresses a sibling component on this same game object.
      msg.post("#animator", "play_animation", { id: hash("jump") });
    }
  },
});
```

Confirm each id names a real component and the snippet builds — see
[Verify against the real API surface](#verify-against-the-real-api-surface).

#### Spawn objects with a factory

**Goal:** create new game objects at runtime from a prototype.

Add a `.factory` component to a game object and point it at the prototype `.go`.
At runtime, `factory.create(url, position?, rotation?, properties?, scale?)`
returns the spawned object's id as a `Hash`. The fourth argument, `properties`,
seeds the new script's `self` before its `init` runs, so each spawned instance
can start with its own state.

```ts
import { defineScript } from "@defold-typescript/types";

export default defineScript({
  init() {
    // properties (4th arg) seed the spawned script's self before its init runs.
    const enemy = factory.create("#enemyfactory", undefined, undefined, {
      health: 100,
    });
    return { lastSpawned: enemy };
  },
});
```

Confirm `factory.create` against
`node_modules/@defold-typescript/types/generated/factory.d.ts` and build the
snippet — see [Verify against the real API surface](#verify-against-the-real-api-surface).

#### Spawn a hierarchy with a collection factory

**Goal:** spawn a whole tree of game objects in one call.

A `.collectionfactory` component points at a `.collection`. Unlike `factory`,
`collectionfactory.create(url, position?, rotation?, properties?, scale?)` returns
a `LuaMap<Hash, Hash>` mapping each prototype id in the collection to the runtime
id it was spawned as. Read one spawned object out of the map with
`.get(prototypeId)`, keyed by the `/`-prefixed path the collection gives it.

```ts
import { defineScript } from "@defold-typescript/types";

export default defineScript({
  init() {
    const ids = collectionfactory.create("#levelfactory");
    // Read one spawned object out of the map by its prototype id.
    const player = ids.get(hash("/player"));
    return { player };
  },
});
```

Confirm `collectionfactory.create` against
`node_modules/@defold-typescript/types/generated/collectionfactory.d.ts` and build
the snippet — see [Verify against the real API surface](#verify-against-the-real-api-surface).

#### Pass messages between components

**Goal:** send a message from one component to another and receive it typed.

`msg.post(receiver, message_id, message?)` addresses the receiver by a URL
string. Two forms cover most cases: `"#component"` reaches a sibling component on
the *same* game object, and `"/object#component"` reaches a named component on a
*different* object. The receiver handles it in `on_message`; to narrow the
untyped payload by `message_id` without `typeof`/`as`, reuse the guard from
[Narrow engine callback payloads](#narrow-engine-callback-payloads) rather than
re-deriving it here.

```ts
import { defineScript } from "@defold-typescript/types";

export default defineScript({
  update(self) {
    // "#…" → sibling on this object; "/path#…" → a component on another object.
    msg.post("#health", "damage", { amount: 10 });
    msg.post("/enemy#ai", "alert");
  },
});
```

Confirm each address resolves and the snippet builds — see
[Verify against the real API surface](#verify-against-the-real-api-surface).

#### Address an object by URL

**Goal:** pick the right URL form for every `msg.post` / `go.get` / `go.set` /
`msg.url` call, and know when the `socket:` prefix is required.

A Defold URL is `[socket:][path][#fragment]` — the first part is optional. Inside
a single world (everything in your bootstrap collection) address by relative id,
absolute path, or sibling component, with **no** `socket:`:

- `"camera"` — a sibling instance by id, resolved relative to the current component.
- `"/camera"` — the same instance by id, absolute from the current world's root.
- `"#health"` — a sibling component on the *same* game object.
- `"/enemy#ai"` — a named component on a different object in the same world.

The `socket:` segment is reserved for crossing into a **collection-proxy-loaded
world**: `msg.post("level_a:/door#sensor", "open")` reaches `door#sensor` in the
collection whose `Name` property is `level_a`. That value is the *target*
collection's `Name`, not the proxy component's id — and a collection's `Name` is
a field distinct from its folder, so a bare `"main:…"` copied from a Lua example
is fragile (it assumes your bootstrap collection happens to be named `main`).

The two-arg `msg.url(socket, path, fragment)` call is a runtime error — only
`msg.url()`, `msg.url(urlstring)`, and the all-required three-arg form are
supported. The tightened overloads in `msg-overloads.d.ts` reject the two-arg
form at compile time, so the typings are the warning.

Confirm every address resolves and the snippet builds — see
[Verify against the real API surface](#verify-against-the-real-api-surface). For
the full address grammar and the cross-world proxy case, follow up with the
[TypeScript gotchas URL addressing entry](./typescript-gotchas.md#url-addressing-same-world-objects-are-relative-socket-crosses-worlds).

#### Where script state lives

**Goal:** decide whether a piece of mutable state belongs on `self` or in a
module.

Per-instance state belongs on the typed `self`: `init`'s returned object is
copied onto `self` for *that* component instance, so two objects running the same
script keep independent values. A module-level `let`/`const` behaves differently,
and the build shows how — this source:

```ts
import { defineScript } from "@defold-typescript/types";

// Module-level: one value, not per-instance.
let spawnCount = 0;

export default defineScript({
  init() {
    // Per-instance: copied onto this component's self.
    return { health: 100 };
  },
  update(self) {
    self.health -= 1;
    spawnCount += 1;
  },
});
```

compiles `spawnCount` to a single Lua **module local** evaluated once, while
`health` is assigned onto each instance's `self`:

```lua
local spawnCount = 0
function init(self)
    -- self.health is set per instance
end
function update(____self)
    ____self.health = ____self.health - 1
    spawnCount = spawnCount + 1
end
```

Because Defold loads each module once via `require` and caches it, that module
local is **shared by every component instance that requires the module** — it is
not per-instance state. Reach for a module local only for constants or a
deliberately-shared singleton; keep anything each instance must own its own copy
of on `self`. The full `self` typing model — how `init` infers it and how
`properties` seed it — is in [Script lifecycle](./script-lifecycle.md).

Above a module local sits one wider tier: a **VM-global** declared with `declare
global`. The declaration emits no Lua; a use site lowers to a bare Lua global
shared across the entire VM — no `require`, no module scope:

```lua
function ____exports.bump()
    FOO = FOO + 1
    return FOO
end
```

No `local FOO` and no `____exports.` prefix — `FOO` is raw VM-wide state, broader
than a cached module local. Reach for it only for genuine engine/Lua globals;
prefer a module singleton for app state. The full four-tier treatment — per-instance
`self`, shared module local, cross-script module singleton, and VM-global — is in
[Where script state lives](./script-state.md).

### Helper scripts

Build tools, codegen, and one-off maintenance scripts belong **outside** your
Defold source tree, in a project-root `/scripts` folder, and run with **Bun**.
This keeps them off the Lua build path and gives them Node-style typings without
polluting the types your game code sees.

#### Run with Bun, never `node`

Run a helper script with Bun:

```sh
bun scripts/generate-levels.ts
```

The `node:*` builtins — `node:fs`, `node:path`, `node:child_process`, and the
rest — work under Bun unchanged; `@types/bun` types them. There is no reason to
reach for the `node` binary, and doing so skips the TypeScript execution Bun
gives you for free.

#### Put them in `/scripts`, not `src/`

Keep helper scripts in a `/scripts` folder at the project root. **Do not** put
them under `src/` — the Defold build compiles source by `tsconfig.include`
(default `src/**/*.ts`) and **ignores `exclude`**, so any `.ts` file under
`src/**` is transpiled to Lua and shipped into your game, whether you meant it
to be or not.

`src/` is also the wrong place for typing: the scaffolded `tsconfig.json` pins
`compilerOptions.types` to `["@defold-typescript/types"]` so your game code sees
the Defold API and nothing else. A build script that imports `node:fs` under
that pin would not type-check.

A project-root `/scripts` folder sits outside both the `src/**` include and the
main `tsconfig.json`, so a dedicated `scripts/tsconfig.json` with its own `types`
gives Bun typing with zero changes to your game's compile.

#### Type them with `scripts/tsconfig.json`

Add a `scripts/tsconfig.json` that types the folder for Bun. Do **not** re-pin
the Defold types here — these scripts are not Defold code:

```json
{
  "compilerOptions": {
    "noEmit": true,
    "types": ["bun"]
  },
  "include": ["**/*.ts"]
}
```

`noEmit` because Bun runs the TypeScript directly — nothing is compiled to disk.
`types: ["bun"]` swaps the Defold API surface for the Bun and `node:*` typings.
Editors auto-discover the file for anything under `scripts/`, so your helper
scripts get autocomplete and `tsc` coverage on their own terms.

#### Script dependencies go in the root `package.json`

Any package a helper script needs is a dev-time dependency of the project, not a
runtime dependency of your game. Add it to the root `package.json`
`devDependencies` (`@types/bun` is already there in a scaffolded project):

```sh
bun add -d fast-glob
```

#### A minimal example

```ts
import { readdir } from "node:fs/promises";

const files = await readdir("assets/levels");
console.log(`${files.length} level files`);
```

Run it with `bun scripts/count-levels.ts`. It imports a `node:*` builtin, is
typed by `scripts/tsconfig.json`, and never touches the Lua build.

### Pinning the Defold API version

`@defold-typescript/types` ships the **latest/current** Defold API surface
pre-baked, and generates older versioned surfaces on demand. The default import
is always the current surface; opting into an older version generates that
version's surface on your machine and materializes it locally. Pinning a surface
makes the TypeScript compiler reject calls to engine functions that do not exist
in the Defold version you target, instead of letting them through to fail at
runtime.

#### The default stays current

If you do nothing, you get the current surface — the same behaviour as before
versioning existed:

```jsonc
// tsconfig.json
{
  "compilerOptions": {
    "types": ["@defold-typescript/types"]
  }
}
```

This is unchanged for existing projects. The default surface tracks the latest
generated API.

#### Opting into a pinned surface

You do not pin a surface through a package subpath export. Versioned surfaces
are **not** shipped pre-baked in the npm package — only the current-stable
surface is. A non-current version's `.d.ts` are generated on your machine the
moment you pin it (from that version's Defold reference docs) and
**materialized** into a project-local `.defold-types/<version>/` faux `@types`
package that your `tsconfig.json` references.

You select the version with the `package.json` pin described below; the
toolchain resolves it, generates the matching surface, and repoints
`tsconfig.json` at the materialized package. A function that exists only on the
current surface is then a compile error against an older pin, while functions
shared across versions continue to type-check.

#### Recording the project's Defold version

A Defold project pins a fixed engine version, but that version is not stored
anywhere in the project tree — not in `game.project`, not in build artifacts,
not in editor metadata. You declare it in `package.json` under the
`defold-typescript` namespace:

```jsonc
// package.json
{
  "defold-typescript": { "defold-version": "1.12.4" }
}
```

`bunx @defold-typescript/cli@latest init <folder>` seeds this key with the current-stable version when it
creates or augments a `package.json`, and leaves an existing pin untouched.

The active version resolves with this precedence:

1. `--defold-version <version>` on the command line (highest),
2. the `package.json` pin,
3. the **installed Defold editor's `version`** (lowest-precedence fallback),
4. the current-stable default.

The installed-editor detection reads the editor bundle's `config` file from
its conventional per-OS location (for example
`/Applications/Defold.app/Contents/Resources/config` on macOS,
`~/Defold/config` on Linux, `%LOCALAPPDATA%\Defold\config` or
`%PROGRAMFILES%\Defold\config` on Windows), parses the `version = ...` line,
and uses that value when no flag or pin is present. The first candidate that
parses wins, and an unknown platform — or no editor installed — reports
`detected: null` and falls through to the current-stable default. The exact
bundle paths are pinned for live verification against a real install; the
probe mechanics (per-OS candidate order, parse, hit/miss) are unit-tested
synthetically and the production reader is an injectable seam.

The resolved version is reported in `--json` output as `defoldVersion`, and the
surface it maps to is reported alongside it as `apiSurface`. The current-stable
version maps to the default surface (`apiSurface: "defold-1.12.4"`); a version with a
registered reference-doc target maps to `apiSurface: "defold-<version>"` (for
example `defold-1.9.8`); a version with no matching target reports
`apiSurface: null`. The source that resolved the version is reported as
`defoldVersionSource` (`flag` / `pin` / `detected` / `default`), so an agent
script can tell whether the version came from the command line, the
`package.json` pin, the installed editor, or the hardcoded default.

#### Materializing the pinned surface

`bunx @defold-typescript/cli build` does not only report the surface — it **materializes**
it. The build writes a project-local `.defold-types/<surface>/` directory (a faux
`@types` package with its own `index.d.ts` and `package.json`), then repoints
`tsconfig.json` at it so exactly one surface is the active ambient type surface:

```jsonc
// tsconfig.json (rewritten by build)
{
  "compilerOptions": {
    "typeRoots": [".defold-types"],
    "types": ["defold-1.9.8"]
  }
}
```

How the surface is produced depends on the resolved version:

- **Current-stable** copies the pre-baked surface that ships in
  `@defold-typescript/types` into `.defold-types/defold-1.12.4/`. No network access.
- **A pinned non-current version** is generated **on the fly** from that
  version's Defold reference docs and written into
  `.defold-types/<version>/` (for example `.defold-types/defold-1.9.8/`). The
  reference docs are downloaded once on first use and cached, so later builds
  are offline. The generated faux package carries a `core-types.d.ts` that
  re-exports the installed `@defold-typescript/types/core-types`, so its branded
  engine types stay unified with the ones your code imports rather than minting a
  nominally distinct copy. It also carries `engine-globals.d.ts` and side-effect imports it from
  the surface `index.d.ts`, so the engine types (`Vector3`, `Hash`, `Url`, …)
  are ambient globals — name them with no import, matching the namespace
  ergonomics (`vmath`, `go`, …).

The `.defold-types/` directory is generated output, so build adds it to the
project `.gitignore`. The materialized directory is reported in `--json` output
as `materializedSurface`. Re-running build is idempotent.

The pinned versioned surface is materialized in full — `build` and `watch` never
narrow it by script kind. Narrowing a directory to one kind is opt-in via the
`wall` command; see [Wall](wall.md) and the per-kind API wall in
[Script lifecycle](script-lifecycle.md). (Walls today narrow against the
installed `@defold-typescript/types` subpaths, not the pinned
`.defold-types/<version>/` surface.)

If a pinned version cannot be generated — an unknown version, or no network on
first use — the build does **not** fail. It reports `materializedSurface: null`,
warns on stderr, leaves `tsconfig.json` untouched, and exits `0`; the default
committed surface stays usable. Having Bun is enough to compile your project.

#### Pinning a release channel

A Defold release channel picks which build of the engine the reference docs
are fetched from. Three channels are supported — `stable` (the default),
`beta`, and `alpha`. The `stable` channel is the production release line; the
`beta` and `alpha` channels are experimental pre-release surfaces that track
in-development builds and may break at any time. If you do nothing, the
default stays `stable`; existing projects with no channel pin are unchanged.

You select a channel the same way you select a version — by name — and the
channel rides the same precedence chain. The `--channel` flag overrides the
`package.json` pin, and the pin overrides the `stable` default:

1. `--channel <channel>` on the command line (highest),
2. the `package.json` `defold-typescript.channel` pin,
3. the `stable` default.

```jsonc
// package.json
{
  "defold-typescript": {
    "defold-version": "1.12.4",
    "channel": "stable"
  }
}
```

`bunx @defold-typescript/cli@latest init <folder>` does not seed a `channel` key, so a
project with no pin behaves exactly as today. The resolved channel is reported
in `--json` output as `defoldChannel` on `init` and `build`. `init` reports the
default `stable` without writing the key, so the key stays absent unless you
pin it yourself.

How the channel affects the doc-source fetch:

- **`stable`** downloads `ref-doc.zip` directly from the pinned `defold-version`'s
  GitHub release assets (`releases/download/<version>/ref-doc.zip`) — no
  `engine/share/` path. This is the only path that touches the GitHub release
  archive directly.
- **`beta`** and **`alpha`** resolve the channel head via
  `d.defold.com/<channel>/info.json` and download
  `archive/<channel>/<sha1>/engine/share/ref-doc.zip`, cached channel-scoped.
  Each channel's cache directory is independent, so switching channels does
  not invalidate the `stable` cache.

#### Maintainer verification

The public `defold-1.9.8` example target is periodically checked with the
advisory, network-touching `bun run ref-doc-delta` command. It verifies that the
live Defold 1.9.8 reference docs still include `label.get_text` and still omit
`label.set_text`. If the command fails, update the registry target or the example
delta; do not ignore the drift.

### 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 an ambient TypeScript namespace for
it — 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 with no import.

#### Declaring an extension

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

```ini
[project]
title = My Game

[dependencies]
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`](./resolve.md) command reads every `dependencies#N` URL, downloads
and caches each archive, and emits one ambient namespace per `.script_api` doc
into `.defold-types/extensions/`, wiring it into `tsconfig.json`:

```sh
bunx @defold-typescript/cli resolve
```

Run it once after declaring a dependency, and re-run it (or leave
[`watch`](./watch.md) running, which re-resolves on every `game.project` save)
whenever you edit `[dependencies]`. See [Resolve](./resolve.md) for the full
behavior, the `--frozen` lockfile mode, version pinning, and the cache location.

#### Consuming the generated namespace

Each emitted namespace is **ambient**, so you call it with no import — exactly
like the engine namespaces:

```ts
// iap is ambient — resolved through the .defold-types/extensions surface.
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`.

For the command itself — `--frozen`, version pinning, drift detection, and the
cache location — see [Resolve](./resolve.md).

### API docs vs. ts-defold-types

How the JSDoc that `@defold-typescript/types` emits compares with the incumbent
hand-and-script-maintained [thinknathan/ts-defold-types](https://github.com/thinknathan/ts-defold-types).
Both surfaces derive from the **same** Defold reference docs, so symbol coverage
is parity by construction; this page records where `@defold-typescript/types`'
emitted documentation is strictly cleaner, and the one place `ts-defold-types` is
arguably cleaner.

The comparison is backed by a machine check, `packages/types/test/api-doc-parity.test.ts`,
which parses a pinned snapshot of the `ts-defold-types` `index.d.ts` and the
`@defold-typescript/types` `generated/*.d.ts` with one shared extractor and fails
if `@defold-typescript/types` documents **less** than `ts-defold-types` does for
any shared symbol. It compares *documentation*, not type fidelity (branded vs. flat
types are out of scope here).

#### Dimension comparison

| Dimension | ts-defold-types | `@defold-typescript/types` |
| --- | --- | --- |
| Description coverage | Most functions/constants carry a summary | Same source, same coverage; every shared symbol documents at least as well |
| Namespace hover | Module namespaces are not consistently documented | Generated namespaces use Defold module metadata; `(synthesized)` marks fallback prose only when the ref-doc has no module summary |
| `@param` style | `@param <name> <desc>` (no separator) | `@param <name> - <desc>` (dash-separated, the JSDoc convention editors render as a definition list) |
| Description markup | Raw ref-doc text | `htmlToDocText` converts HTML to Markdown: `<code>`→`` `code` ``, `<ul><li>`→`- ` bullets, `<a>`→link text, entities decoded |
| Multi-line `@param`/`@returns` | Continuation lines escape the ` * ` grid | Every continuation line carries ` * ` (see [the well-formedness gate](#well-formedness)) |
| `@returns` | One flat `@returns` even for multi-value returns | One `@returns` for single returns; multi-value returns are typed as a `LuaMultiReturn` tuple that names every value (see [exceptions](#multi-return-functions)) |
| `@example` | `@example <prose>` then a fenced block | `@example` then a fenced ```` ```lua ```` block on its own lines |
| Constant types | `const X: number` | Branded: `number & { readonly __brand: "ns.X" }` — distinct constants stay nominally distinct |

##### Description markup, concretely

ts-defold-types:

```
 * @param options A table with the following fields: <ul><li><code>count</code> ...
```

`@defold-typescript/types`:

```
 * @param options - A table with the following fields:
 * - `count` ...
```

<a id="well-formedness"></a>
##### Well-formedness

A multi-line `@param` doc (a ref-doc `<li>` list becomes embedded newlines) is
re-prefixed line by line so it stays inside the JSDoc ` * ` grid. The permanent
guard for this is the self-contained `packages/types/test/doc-comment-wellformed.test.ts`
gate over the committed `generated/*.d.ts` — it does not depend on the pinned
fixture below.

#### Coverage-test result

Against the pinned snapshot (Defold stable 1.12.4):

- **791 shared symbols** — for every one, the `@defold-typescript/types` docs are
  a superset: if `ts-defold-types` has a description, a `@param`, a `@returns`, or
  an `@example`, `@defold-typescript/types` does too.
- **106 `ts-defold-types`-only symbols** — reported as coverage notes, not
  failures. These are surface-shape differences, not dropped docs: top-level
  globals (`pprint`, `hash`, …) and modules the `@defold-typescript/types` surface
  structures differently (`b2d.body.*`, `bit.*`, some `socket` overloads). They
  live elsewhere or under a different namespace path in the `@defold-typescript/types`
  split, branded/versioned surface.

<a id="multi-return-functions"></a>
##### Multi-return functions

For **9** functions whose Lua API returns several values (e.g.
`gui.get_type`, `gui.new_texture`, `buffer.get_metadata`,
`collectionproxy.set_collection`, `sound.get_rms`, `window.get_size`),
`ts-defold-types` collapses the return to one `@returns` line. `@defold-typescript/types`
instead types the return as a `LuaMultiReturn<[…]>` tuple, so each returned value
is named in the type itself rather than in prose. The coverage test treats these
as documented-by-type, not as a `@returns` regression.

#### Lua standard library reference category

The `/api` reference browser surfaces the Defold-engine namespaces plus a
separate **Lua standard library** category for the pure-Lua / LuaJIT surfaces
Defold documents (`base`, `bit`, `math`, `os`, `string`, `table`,
`coroutine`, `debug`, `io`, `package`). Their TypeScript types come from the
`lua-types` dependency the `lua-stdlib-globals` goal adopted
(`lua-types/special/jit-only.d.ts` for `bit`, `lua-types/core/global.d.ts` for
the base globals, `lua-types/core/debug.d.ts` and `lua-types/core/io.d.ts` for
`debug`/`io`, and `lua-types/core/modules.d.ts` for `package`) and are wired
into every script kind via the
`LUA_STDLIB_REFERENCES` triple-slash directives in `regen.ts` — `@defold-typescript/types`
does **not** re-emit them as generated namespaces (a duplicate `declare
namespace bit` would collide, and the base globals are top-level globals, not a
`base.*` namespace). The category is docs-only: a dedicated
`LUA_STDLIB_MANIFEST` vendors the same ref-doc JSON `SYNC_MANIFEST` carries,
but the docs-site is the only consumer; `regen.ts` / `MODULE_MANIFEST` never
read it, so no `generated/<ns>.d.ts` is produced. The topbar's "Lua standard
library" link leads to `/api/base`; the per-namespace page leads with a
`lua-types` provenance note.

#### Where ts-defold-types is arguably cleaner

One deliberate trade-off runs the other way. The `@defold-typescript/types`
`@example` block extracts the ref-doc `examples` field verbatim into a single
```` ```lua ```` fence — including the example's leading prose sentence (e.g.
*"How to create and initialize a buffer"*), which then sits **inside** the code
fence and is not valid Lua. `ts-defold-types` keeps the fence pure by putting that
prose on the `@example` line itself.

This is the documented slice-4 decision: the ref-doc ships the prose and the code
as one `examples` HTML blob, and splitting prose from code reliably is brittle, so
`@defold-typescript/types` keeps the sample intact and accepts a prose line inside
the fence. Hover still renders the sample; the prose reads as a leading comment.
Reversing this is explicitly out of scope for the parity work.

#### Which surface fits your project

Both surfaces cover the same symbols, so this comes down to which documentation
shape you want in your editor:

- **Reach for `@defold-typescript/types`** if you want Markdown-rendered hovers,
  dash-style `@param`s that editors lay out as a definition list, multi-line docs
  that stay aligned to the JSDoc grid, multi-value returns typed as a named
  `LuaMultiReturn` tuple, and branded constants that stay nominally distinct.
- **Reach for `ts-defold-types`** if its one doc-quality edge matters to you: a
  pure `@example` fence with the prose kept out on the `@example` line.

This is your call, not a verdict — pick the trade-off that reads best for how you
work.

### Migrating from ts-defold

Moving a Defold + TypeScript project from the [ts-defold](https://github.com/ts-defold)
stack (`@ts-defold/types`, `@ts-defold/create`) to `@defold-typescript/*`.

Both stacks compile TypeScript to Lua with [TypeScriptToLua](https://typescripttolua.github.io/)
(TSTL) and derive their Defold API types from the **same** Defold reference docs,
so the code you already wrote — lifecycle callbacks, `vmath`/`go`/`msg` calls,
module imports — carries over with little change. The migration is mostly
tooling and configuration, not a rewrite.

> Every cross-stack claim on this page is verified against a source — see
> [What this guide verified](#what-this-guide-verified) at the bottom, which
> also names what could not be verified and is therefore omitted.

#### What stays the same

- **TypeScriptToLua under the hood.** Both stacks transpile with TSTL, so the
  language subset, the `@typescript-to-lua/language-extensions` helpers, and the
  `lua-types` ambient Lua stdlib are shared concepts. (ts-defold's type bundle
  references `@typescript-to-lua/language-extensions`, `lua-types/5.1`, and
  `lua-types/special/jit-only`.)
- **Ambient engine globals.** In both stacks the Defold API arrives as ambient
  declarations — you call `go`, `msg`, `vmath`, etc. without importing them.
  ts-defold ships this as a `@noSelfInFile` ambient `index.d.ts`;
  `@defold-typescript` ships it as the ambient `@defold-typescript/types`.
- **Same Defold surface.** Both type sets are generated from the same Defold
  reference docs, so symbol coverage is at parity by construction. The
  documentation-quality differences are catalogued separately in
  [API docs vs. ts-defold-types](./api-docs-vs-ts-defold.md).

#### Package and tooling map

| ts-defold                                                                                                               | `@defold-typescript` equivalent                                                                                                     |
| ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `@ts-defold/types` — Defold TypeScript definitions                                                                      | `@defold-typescript/types` — ambient, type-only engine surface                                                                      |
| `@ts-defold/type-gen` — dev-dep that generates those types                                                              | type generation is internal to `@defold-typescript/types`; it is never a consumer dependency                                        |
| `@ts-defold/create` — `npm init @ts-defold my-game` (resolves GitHub `tsd-template-*` templates, or a local/remote zip) | `bunx @defold-typescript/cli@latest init my-game` — built-in templates via `init my-game --template <name>` (`default` / `minimal`) |
| template `npm run build` (compile, no watcher)                                                                          | `defold-typescript build`                                                                                                           |
| template `npm run dev` (watch: compile + emit lua/script on save)                                                       | `defold-typescript watch`                                                                                                           |
| — (no first-party editor-diagnostics package verified)                                                                  | `@defold-typescript/tstl-plugin` — live transpile diagnostics in the editor                                                         |

The full `defold-typescript` command surface is
`init | init-agents | build | watch | wall | setup-debug | resolve | defold`
(and `defold <resolve|build|bundle>`).

#### In-place adoption is a migration strength

Compared with the verified `@ts-defold/create` flow, `defold-typescript init .`
is intentionally optimized for an existing Defold project. When `game.project`
already exists, the command adds the TypeScript toolchain in place instead of
creating a wrapper folder or a new template tree you have to merge back into your
game. That is the main practical advantage for teams migrating a real project:
assets, collections, scripts, and editor paths stay where they are while the TypeScript
surface is layered on top.

#### Step-by-step migration

These steps run against an **existing** ts-defold project (a directory that
already has a `game.project`).

1. **Add the defold-typescript toolchain in place.** From the project root, run
   `bunx @defold-typescript/cli@latest init .` (the `.` targets the current
   folder; `init` requires an explicit destination). With a `game.project` present,
   `init` runs in *add-TypeScript mode*: it writes only the TypeScript surface
   (a `tsconfig.json`, dev-deps merged into `package.json`, and a `src/main.ts`
   only if one does not already exist) and refuses to overwrite a conflicting
   TS config unless you pass `--force`. Your existing `src/*.ts` and
   `game.project` are left alone.
2. **Reconcile `tsconfig.json`.** The defold-typescript scaffold sets `target: ES2022`,
   `module: ESNext`, `moduleResolution: Bundler`, `types: ["@defold-typescript/types"]`,
   and `plugins: [{ name: "@defold-typescript/tstl-plugin" }]`. Point the
   `types` array at `@defold-typescript/types` (replacing `@ts-defold/types`)
   and add the `tstl-plugin` entry to keep live editor diagnostics.
3. **Build with the defold-typescript CLI.** Run `defold-typescript build` (or
   `defold-typescript watch` for the save-loop). The transpiler targets
   **Lua 5.1**. Compiled output is written **beside the source** as
   `src/**/*.ts.script`, `*.ts.gui_script`, `*.ts.render_script` (plus `*.lua`
   and `*.map` sidecars) — see [Defold editor](./defold-editor.md) for attaching
   the compiled component.
4. **Keep the editor loop.** `@defold-typescript/tstl-plugin` surfaces
   transpile errors live in the editor without ever failing `tsc --noEmit`
   (see [Live transpile diagnostics](./transpile-diagnostics.md)); for
   step-through debugging use `defold-typescript setup-debug` and
   [Debugging](./debugging.md).

> Your ts-defold project's own `tsconfig.json` (its TSTL `luaTarget`,
> `luaLibImport`, `outDir`, and plugin list) is the other half of this
> reconcile. Those values are project-specific and are **not** asserted here —
> open your template's `tsconfig.json` and map each key to the defold-typescript
> scaffold above.

#### Type-surface differences you will hit

Symbol coverage is at parity, but the `@defold-typescript` surface shapes a few things differently.
These are the porting touch-points; the deep comparison lives in
[API docs vs. ts-defold-types](./api-docs-vs-ts-defold.md) and the runtime
narrowing traps in [TypeScript gotchas](./typescript-gotchas.md).

- **Branded constants.** Where ts-defold types a constant as `const X: number`,
  `@defold-typescript/types` brands it (`number & { readonly __brand: "ns.X" }`) so distinct
  constants stay nominally distinct. Code that passed a raw `number` where a
  branded constant is expected may need the constant itself, not a literal.
- **Multi-value returns are typed tuples.** Functions whose Lua API returns
  several values are typed as `LuaMultiReturn<[…]>` (each value named in the
  type), not collapsed to one return.
- **Per-kind ambient API walls.** Beyond the bare `@defold-typescript/types`
  entry, `@defold-typescript` exposes per-script-kind surfaces — `@defold-typescript/types/script`,
  `/gui-script`, `/render-script` — so a GUI script only sees the GUI-legal API.
- **Opaque handles.** Most engine handles are branded opaque types rather than
  bare aliases; `typeof`-narrowing cannot see them (they are Lua `userdata`). The
  exception is socket handles (`client`, `master`, `server`, `connected`,
  `unconnected`), emitted as method-bearing interfaces so their documented colon
  methods (`client:send`, …) are reachable and the receivers stay distinct.

#### What this guide verified

**@defold-typescript side** (this repository): packages and the `defold-typescript` command
surface from `packages/cli/src/dispatch.ts`; the `init` add-TS mode and scaffold
`tsconfig.json` from `packages/cli/src/init.ts`; the Lua 5.1 transpiler target
from `packages/transpiler/src/session.ts` and `transpile.ts`; the compiled-output
naming from the scaffold `.gitignore`; the per-kind type entrypoints from
`packages/types/package.json`.

**ts-defold side:**
- *Type surface* — the pinned snapshot `packages/types/test/fixtures/ts-defold-types.index.d.ts`
  (thinknathan/ts-defold-types commit `4f0672a`, Defold stable 1.12.4, pinned 2026-06-05):
  `@noSelfInFile`; references `@typescript-to-lua/language-extensions`,
  `lua-types/5.1`, `lua-types/special/jit-only`, `deprecated.d.ts`.
- *Tooling* — verified 2026-06-14 against [ts-defold/create](https://github.com/ts-defold/create)
  and [ts-defold/types](https://github.com/ts-defold/types): the
  `npm init @ts-defold <dir> [-- --template <name>]` scaffolder, the
  `tsd-template-*` GitHub discovery pattern, the template `npm run build`
  (compile) / `npm run dev` (watch) scripts, and [TypeScriptToLua](https://typescripttolua.github.io/) (TSTL)
  as the transpiler.

**Omitted as unverifiable here:** the exact contents of a ts-defold template's
`tsconfig.json` (its `luaTarget`, `luaLibImport`, `outDir`, plugin list) — the
upstream template's config file could not be read at authoring time, so this
guide does not assert those values; consult your own template's `tsconfig.json`.

## API

### globals

- hash(s: string): Hash
- hash_to_hex(h: Hash): string
- pprint(v: unknown)

### b2d

- b2d.get_world(): Opaque<"b2World">
- b2d.get_body(url: string | Hash | Url): Opaque<"b2Body">

### b2d.body

- b2d.body.set_transform(body: Opaque<"b2Body">, position: Vector3, angle: number)
- b2d.body.get_position(body: Opaque<"b2Body">): Vector3
- b2d.body.get_angle(body: Opaque<"b2Body">): number
- b2d.body.get_world_center_of_mass(body: Opaque<"b2Body">): Vector3
- b2d.body.get_local_center_of_mass(body: Opaque<"b2Body">): Vector3
- b2d.body.set_linear_velocity(body: Opaque<"b2Body">, velocity: Vector3)
- b2d.body.get_linear_velocity(body: Opaque<"b2Body">): Vector3
- b2d.body.set_angular_velocity(body: Opaque<"b2Body">, omega: number)
- b2d.body.get_angular_velocity(body: Opaque<"b2Body">): number
- b2d.body.apply_force(body: Opaque<"b2Body">, force: Vector3, point: Vector3)
- b2d.body.apply_force_to_center(body: Opaque<"b2Body">, force: Vector3)
- b2d.body.apply_torque(body: Opaque<"b2Body">, torque: number)
- b2d.body.apply_linear_impulse(body: Opaque<"b2Body">, impulse: Vector3, point: Vector3)
- b2d.body.apply_angular_impulse(body: Opaque<"b2Body">, impulse: number)
- b2d.body.get_mass(body: Opaque<"b2Body">): number
- b2d.body.get_rotational_inertia(body: Opaque<"b2Body">): number
- b2d.body.reset_mass_data(body: Opaque<"b2Body">)
- b2d.body.get_world_point(body: Opaque<"b2Body">, local_vector: Vector3): Vector3
- b2d.body.get_world_vector(body: Opaque<"b2Body">, local_vector: Vector3): Vector3
- b2d.body.get_local_point(body: Opaque<"b2Body">, world_point: Vector3): Vector3
- b2d.body.get_local_vector(body: Opaque<"b2Body">, world_vector: Vector3): Vector3
- b2d.body.get_linear_velocity_from_world_point(body: Opaque<"b2Body">, world_point: Vector3): Vector3
- b2d.body.get_linear_velocity_from_local_point(body: Opaque<"b2Body">, local_point: Vector3): Vector3
- b2d.body.set_linear_damping(body: Opaque<"b2Body">, damping: number)
- b2d.body.get_linear_damping(body: Opaque<"b2Body">): number
- b2d.body.set_angular_damping(body: Opaque<"b2Body">, damping: number)
- b2d.body.get_angular_damping(body: Opaque<"b2Body">): number
- b2d.body.set_gravity_scale(body: Opaque<"b2Body">, scale: number)
- b2d.body.get_gravity_scale(body: Opaque<"b2Body">): number
- b2d.body.set_type(body: Opaque<"b2Body">, type: (number & { readonly __brand: "b2d.body.B2_DYNAMIC_BODY" }) | (number & { readonly __brand: "b2d.body.B2_KINEMATIC_BODY" }) | (number & { readonly __brand: "b2d.body.B2_STATIC_BODY" }))
- b2d.body.get_type(body: Opaque<"b2Body">): (number & { readonly __brand: "b2d.body.B2_DYNAMIC_BODY" }) | (number & { readonly __brand: "b2d.body.B2_KINEMATIC_BODY" }) | (number & { readonly __brand: "b2d.body.B2_STATIC_BODY" })
- b2d.body.set_bullet(body: Opaque<"b2Body">, enable: boolean)
- b2d.body.is_bullet(body: Opaque<"b2Body">): boolean
- b2d.body.enable_sleep(body: Opaque<"b2Body">, enable: boolean)
- b2d.body.is_sleeping_enabled(body: Opaque<"b2Body">): boolean
- b2d.body.set_awake(body: Opaque<"b2Body">, enable: boolean)
- b2d.body.is_awake(body: Opaque<"b2Body">): boolean
- b2d.body.set_active(body: Opaque<"b2Body">, enable: boolean)
- b2d.body.is_active(body: Opaque<"b2Body">): boolean
- b2d.body.set_fixed_rotation(body: Opaque<"b2Body">, enable: boolean)
- b2d.body.is_fixed_rotation(body: Opaque<"b2Body">): boolean
- b2d.body.get_world(body: Opaque<"b2Body">): Opaque<"b2World">
- b2d.body.B2_STATIC_BODY
- b2d.body.B2_KINEMATIC_BODY
- b2d.body.B2_DYNAMIC_BODY

### buffer

- buffer.create(element_count: number, declaration: Record<string | number, unknown>): Opaque<"buffer">
- buffer.get_stream(buffer: Opaque<"buffer">, stream_name: Hash | string): Opaque<"bufferstream"> & { [index: number]: number }
- buffer.copy_stream(dst: Opaque<"bufferstream"> & { [index: number]: number }, dstoffset: number, src: Opaque<"bufferstream"> & { [index: number]: number }, srcoffset: number, count: number)
- buffer.copy_buffer(dst: Opaque<"buffer">, dstoffset: number, src: Opaque<"buffer">, srcoffset: number, count: number)
- buffer.get_bytes(buffer: Opaque<"buffer">, stream_name: Hash): string
- buffer.set_metadata(buf: Opaque<"buffer">, metadata_name: Hash | string, values: Record<string | number, unknown>, value_type: Opaque<"constant">)
- buffer.get_metadata(buf: Opaque<"buffer">, metadata_name: Hash | string): Record<string | number, unknown> | nil, Opaque<"constant"> | nil
- buffer.VALUE_TYPE_UINT8
- buffer.VALUE_TYPE_UINT16
- buffer.VALUE_TYPE_UINT32
- buffer.VALUE_TYPE_UINT64
- buffer.VALUE_TYPE_INT8
- buffer.VALUE_TYPE_INT16
- buffer.VALUE_TYPE_INT32
- buffer.VALUE_TYPE_INT64
- buffer.VALUE_TYPE_FLOAT32

### camera

- camera.screen_xy_to_world(x: number, y: number, camera?: Url | number | nil): Vector3
- camera.screen_to_world(pos: Vector3, camera?: Url | number | nil): Vector3
- camera.world_to_screen(world_pos: Vector3, camera?: Url | number | nil): Vector3
- camera.get_cameras(): Record<string | number, unknown>
- camera.get_enabled(camera: Url | number | nil): boolean
- camera.get_projection(camera: Url | number | nil): Matrix4
- camera.get_view(camera: Url | number | nil): Matrix4
- camera.get_aspect_ratio(camera: Url | number | nil): number
- camera.get_far_z(camera: Url | number | nil): number
- camera.get_fov(camera: Url | number | nil): number
- camera.get_near_z(camera: Url | number | nil): number
- camera.get_orthographic_zoom(camera: Url | number | nil): number
- camera.set_aspect_ratio(camera: Url | number | nil, aspect_ratio: number)
- camera.set_far_z(camera: Url | number | nil, far_z: number)
- camera.set_fov(camera: Url | number | nil, fov: number)
- camera.set_near_z(camera: Url | number | nil, near_z: number)
- camera.set_orthographic_zoom(camera: Url | number | nil, orthographic_zoom: number)
- camera.get_orthographic_mode(camera: Url | number | nil): number
- camera.set_orthographic_mode(camera: Url | number | nil, mode: number)
- camera.get_auto_aspect_ratio(camera: Url | number | nil): boolean
- camera.set_auto_aspect_ratio(camera: Url | number | nil, auto_aspect_ratio: boolean)
- camera.ORTHO_MODE_FIXED
- camera.ORTHO_MODE_AUTO_FIT
- camera.ORTHO_MODE_AUTO_COVER

### collectionfactory

- collectionfactory.get_status(url?: string | Hash | Url): Opaque<"constant">
- collectionfactory.unload(url?: string | Hash | Url)
- collectionfactory.load(url?: string | Hash | Url, complete_function?: function(self, url, result))
- collectionfactory.create(url: string | Hash | Url, position?: Vector3, rotation?: Quaternion, properties?: Record<string | number, unknown>, scale?: number | Vector3): Record<string | number, unknown>
- collectionfactory.set_prototype(url?: string | Hash | Url, prototype?: string | nil)
- collectionfactory.STATUS_UNLOADED
- collectionfactory.STATUS_LOADING
- collectionfactory.STATUS_LOADED

### collectionproxy

- collectionproxy.set_collection(url?: string | Hash | Url, prototype?: string | nil): boolean, number
- collectionproxy.get_resources(collectionproxy: Url): Record<string | number, unknown>
- collectionproxy.RESULT_LOADING
- collectionproxy.RESULT_ALREADY_LOADED
- collectionproxy.RESULT_NOT_EXCLUDED

### crash

- crash.write_dump()
- crash.set_file_path(path: string)
- crash.load_previous(): number | nil
- crash.release(handle: number)
- crash.set_user_field(index: number, value: string)
- crash.get_modules(handle: number): Record<string | number, unknown>
- crash.get_user_field(handle: number, index: number): string
- crash.get_sys_field(handle: number, index: number): string | nil
- crash.get_signum(handle: number): number
- crash.get_backtrace(handle: number): Record<string | number, unknown>
- crash.get_extra_data(handle: number): string
- crash.SYSFIELD_ENGINE_VERSION
- crash.SYSFIELD_ENGINE_HASH
- crash.SYSFIELD_DEVICE_MODEL
- crash.SYSFIELD_MANUFACTURER
- crash.SYSFIELD_SYSTEM_NAME
- crash.SYSFIELD_SYSTEM_VERSION
- crash.SYSFIELD_LANGUAGE
- crash.SYSFIELD_DEVICE_LANGUAGE
- crash.SYSFIELD_TERRITORY
- crash.SYSFIELD_ANDROID_BUILD_FINGERPRINT
- crash.SYSFIELD_MAX
- crash.USERFIELD_MAX
- crash.USERFIELD_SIZE

### factory

- factory.get_status(url?: string | Hash | Url): Opaque<"constant">
- factory.unload(url?: string | Hash | Url)
- factory.load(url?: string | Hash | Url, complete_function?: function(self, url, result))
- factory.create(url: string | Hash | Url, position?: Vector3, rotation?: Quaternion, properties?: Record<string | number, unknown>, scale?: number | Vector3): Hash
- factory.set_prototype(url?: string | Hash | Url, prototype?: string | nil)
- factory.STATUS_UNLOADED
- factory.STATUS_LOADING
- factory.STATUS_LOADED

### font

- font.add_font(fontc: string | Hash, ttf: string | Hash)
- font.remove_font(fontc: string | Hash, ttf: string | Hash)
- font.prewarm_text(fontc: string | Hash, text: string, callback?: function(self, request_id, result, errstring)): number
- font.get_info(fontc: string | Hash): Record<string | number, unknown>

### go

- go.get(url: string | Hash | Url, property: string | Hash, options?: Record<string | number, unknown>): number | boolean | Hash | Url | Vector3 | Vector4 | Quaternion | Opaque<"resource">
- go.set(url: string | Hash | Url, property: string | Hash, value: number | boolean | Hash | Url | Vector3 | Vector4 | Quaternion | Opaque<"resource">, options?: Record<string | number, unknown>)
- go.get_position(id?: string | Hash | Url): Vector3
- go.get_rotation(id?: string | Hash | Url): Quaternion
- go.get_scale(id?: string | Hash | Url): Vector3
- go.get_scale_uniform(id?: string | Hash | Url): number
- go.set_position(position: Vector3, id?: string | Hash | Url)
- go.set_rotation(rotation: Quaternion, id?: string | Hash | Url)
- go.set_scale(scale: number | Vector3, id?: string | Hash | Url)
- go.set_scale_xy(scale: number | Vector3, id?: string | Hash | Url)
- go.set_parent(id?: string | Hash | Url, parent_id?: string | Hash | Url, keep_world_transform?: boolean)
- go.get_parent(id?: string | Hash | Url): Hash | nil
- go.get_world_position(id?: string | Hash | Url): Vector3
- go.get_world_rotation(id?: string | Hash | Url): Quaternion
- go.get_world_scale(id?: string | Hash | Url): Vector3
- go.get_world_scale_uniform(id?: string | Hash | Url): number
- go.get_world_transform(id?: string | Hash | Url): Matrix4
- go.update_world_transform(id?: string | Hash | Url)
- go.get_id(path?: string): Hash
- go.animate(url: string | Hash | Url, property: string | Hash, playback: go.PLAYBACK_ONCE_FORWARD | go.PLAYBACK_ONCE_BACKWARD | go.PLAYBACK_ONCE_PINGPONG | go.PLAYBACK_LOOP_FORWARD | go.PLAYBACK_LOOP_BACKWARD | go.PLAYBACK_LOOP_PINGPONG, to: number | Vector3 | Vector4 | Quaternion, easing: Vector | go.EASING_INBACK | go.EASING_INBOUNCE | go.EASING_INCIRC | go.EASING_INCUBIC | go.EASING_INELASTIC | go.EASING_INEXPO | go.EASING_INOUTBACK | go.EASING_INOUTBOUNCE | go.EASING_INOUTCIRC | go.EASING_INOUTCUBIC | go.EASING_INOUTELASTIC | go.EASING_INOUTEXPO | go.EASING_INOUTQUAD | go.EASING_INOUTQUART | go.EASING_INOUTQUINT | go.EASING_INOUTSINE | go.EASING_INQUAD | go.EASING_INQUART | go.EASING_INQUINT | go.EASING_INSINE | go.EASING_LINEAR | go.EASING_OUTBACK | go.EASING_OUTBOUNCE | go.EASING_OUTCIRC | go.EASING_OUTCUBIC | go.EASING_OUTELASTIC | go.EASING_OUTEXPO | go.EASING_OUTINBACK | go.EASING_OUTINBOUNCE | go.EASING_OUTINCIRC | go.EASING_OUTINCUBIC | go.EASING_OUTINELASTIC | go.EASING_OUTINEXPO | go.EASING_OUTINQUAD | go.EASING_OUTINQUART | go.EASING_OUTINQUINT | go.EASING_OUTINSINE | go.EASING_OUTQUAD | go.EASING_OUTQUART | go.EASING_OUTQUINT | go.EASING_OUTSINE, duration: number, delay?: number, complete_function?: function(self, url, property))
- go.cancel_animations(url: string | Hash | Url, property?: string | Hash)
- go.delete(id?: string | Hash | Url | Record<string | number, unknown>, recursive?: boolean)
- go.property(name: string, value: number | Hash | Url | Vector3 | Vector4 | Quaternion | Opaque<"resource"> | boolean)
- go.exists(url: string | Hash | Url): boolean
- go.world_to_local_position(position: Vector3, url: string | Hash | Url): Vector3
- go.world_to_local_transform(transformation: Matrix4, url: string | Hash | Url): Matrix4
- init(self: Opaque<"userdata">)
- final(self: Opaque<"userdata">)
- update(self: Opaque<"userdata">, dt: number)
- fixed_update(self: Opaque<"userdata">, dt: number)
- late_update(self: Opaque<"userdata">, dt: number)
- on_message(self: Opaque<"userdata">, message_id: Hash, message: Record<string | number, unknown>, sender: Url)
- on_input(self: Opaque<"userdata">, action_id: Hash, action: Record<string | number, unknown>): boolean | nil
- on_reload(self: Opaque<"userdata">)
- go.PLAYBACK_NONE
- go.PLAYBACK_ONCE_FORWARD
- go.PLAYBACK_ONCE_BACKWARD
- go.PLAYBACK_ONCE_PINGPONG
- go.PLAYBACK_LOOP_FORWARD
- go.PLAYBACK_LOOP_BACKWARD
- go.PLAYBACK_LOOP_PINGPONG
- go.EASING_LINEAR
- go.EASING_INQUAD
- go.EASING_OUTQUAD
- go.EASING_INOUTQUAD
- go.EASING_OUTINQUAD
- go.EASING_INCUBIC
- go.EASING_OUTCUBIC
- go.EASING_INOUTCUBIC
- go.EASING_OUTINCUBIC
- go.EASING_INQUART
- go.EASING_OUTQUART
- go.EASING_INOUTQUART
- go.EASING_OUTINQUART
- go.EASING_INQUINT
- go.EASING_OUTQUINT
- go.EASING_INOUTQUINT
- go.EASING_OUTINQUINT
- go.EASING_INSINE
- go.EASING_OUTSINE
- go.EASING_INOUTSINE
- go.EASING_OUTINSINE
- go.EASING_INEXPO
- go.EASING_OUTEXPO
- go.EASING_INOUTEXPO
- go.EASING_OUTINEXPO
- go.EASING_INCIRC
- go.EASING_OUTCIRC
- go.EASING_INOUTCIRC
- go.EASING_OUTINCIRC
- go.EASING_INELASTIC
- go.EASING_OUTELASTIC
- go.EASING_INOUTELASTIC
- go.EASING_OUTINELASTIC
- go.EASING_INBACK
- go.EASING_OUTBACK
- go.EASING_INOUTBACK
- go.EASING_OUTINBACK
- go.EASING_INBOUNCE
- go.EASING_OUTBOUNCE
- go.EASING_INOUTBOUNCE
- go.EASING_OUTINBOUNCE
- position: Vector3
- rotation: Quaternion
- euler: Vector3
- scale: number

### graphics

- graphics.BUFFER_TYPE_COLOR0_BIT
- graphics.BUFFER_TYPE_DEPTH_BIT
- graphics.BUFFER_TYPE_STENCIL_BIT
- graphics.BUFFER_TYPE_COLOR1_BIT
- graphics.BUFFER_TYPE_COLOR2_BIT
- graphics.BUFFER_TYPE_COLOR3_BIT
- graphics.STATE_DEPTH_TEST
- graphics.STATE_SCISSOR_TEST
- graphics.STATE_STENCIL_TEST
- graphics.STATE_ALPHA_TEST
- graphics.STATE_BLEND
- graphics.STATE_CULL_FACE
- graphics.STATE_POLYGON_OFFSET_FILL
- graphics.STATE_ALPHA_TEST_SUPPORTED
- graphics.BLEND_FACTOR_ZERO
- graphics.BLEND_FACTOR_ONE
- graphics.BLEND_FACTOR_SRC_COLOR
- graphics.BLEND_FACTOR_ONE_MINUS_SRC_COLOR
- graphics.BLEND_FACTOR_DST_COLOR
- graphics.BLEND_FACTOR_ONE_MINUS_DST_COLOR
- graphics.BLEND_FACTOR_SRC_ALPHA
- graphics.BLEND_FACTOR_ONE_MINUS_SRC_ALPHA
- graphics.BLEND_FACTOR_DST_ALPHA
- graphics.BLEND_FACTOR_ONE_MINUS_DST_ALPHA
- graphics.BLEND_FACTOR_SRC_ALPHA_SATURATE
- graphics.BLEND_FACTOR_CONSTANT_COLOR
- graphics.BLEND_FACTOR_ONE_MINUS_CONSTANT_COLOR
- graphics.BLEND_FACTOR_CONSTANT_ALPHA
- graphics.BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA
- graphics.COMPARE_FUNC_NEVER
- graphics.COMPARE_FUNC_LESS
- graphics.COMPARE_FUNC_LEQUAL
- graphics.COMPARE_FUNC_GREATER
- graphics.COMPARE_FUNC_GEQUAL
- graphics.COMPARE_FUNC_EQUAL
- graphics.COMPARE_FUNC_NOTEQUAL
- graphics.COMPARE_FUNC_ALWAYS
- graphics.STENCIL_OP_KEEP
- graphics.STENCIL_OP_ZERO
- graphics.STENCIL_OP_REPLACE
- graphics.STENCIL_OP_INCR
- graphics.STENCIL_OP_INCR_WRAP
- graphics.STENCIL_OP_DECR
- graphics.STENCIL_OP_DECR_WRAP
- graphics.STENCIL_OP_INVERT
- graphics.FACE_TYPE_FRONT
- graphics.FACE_TYPE_BACK
- graphics.FACE_TYPE_FRONT_AND_BACK
- graphics.TEXTURE_TYPE_2D
- graphics.TEXTURE_TYPE_2D_ARRAY
- graphics.TEXTURE_TYPE_CUBE_MAP
- graphics.TEXTURE_TYPE_IMAGE_2D
- graphics.TEXTURE_TYPE_3D
- graphics.TEXTURE_TYPE_IMAGE_3D
- graphics.TEXTURE_FILTER_DEFAULT
- graphics.TEXTURE_FILTER_NEAREST
- graphics.TEXTURE_FILTER_LINEAR
- graphics.TEXTURE_FILTER_NEAREST_MIPMAP_NEAREST
- graphics.TEXTURE_FILTER_NEAREST_MIPMAP_LINEAR
- graphics.TEXTURE_FILTER_LINEAR_MIPMAP_NEAREST
- graphics.TEXTURE_FILTER_LINEAR_MIPMAP_LINEAR
- graphics.TEXTURE_USAGE_FLAG_SAMPLE
- graphics.TEXTURE_USAGE_FLAG_MEMORYLESS
- graphics.TEXTURE_USAGE_FLAG_STORAGE
- graphics.TEXTURE_USAGE_FLAG_INPUT
- graphics.TEXTURE_USAGE_FLAG_COLOR
- graphics.TEXTURE_WRAP_CLAMP_TO_BORDER
- graphics.TEXTURE_WRAP_CLAMP_TO_EDGE
- graphics.TEXTURE_WRAP_MIRRORED_REPEAT
- graphics.TEXTURE_WRAP_REPEAT
- graphics.COMPRESSION_TYPE_DEFAULT
- graphics.COMPRESSION_TYPE_WEBP
- graphics.COMPRESSION_TYPE_WEBP_LOSSY
- graphics.COMPRESSION_TYPE_BASIS_UASTC
- graphics.COMPRESSION_TYPE_BASIS_ETC1S
- graphics.TEXTURE_FORMAT_DEPTH
- graphics.TEXTURE_FORMAT_STENCIL
- graphics.TEXTURE_FORMAT_LUMINANCE
- graphics.TEXTURE_FORMAT_LUMINANCE_ALPHA
- graphics.TEXTURE_FORMAT_RGB
- graphics.TEXTURE_FORMAT_RGBA
- graphics.TEXTURE_FORMAT_RGB_16BPP
- graphics.TEXTURE_FORMAT_RGBA_16BPP
- graphics.TEXTURE_FORMAT_RGB_PVRTC_2BPPV1
- graphics.TEXTURE_FORMAT_RGB_PVRTC_4BPPV1
- graphics.TEXTURE_FORMAT_RGBA_PVRTC_2BPPV1
- graphics.TEXTURE_FORMAT_RGBA_PVRTC_4BPPV1
- graphics.TEXTURE_FORMAT_RGB_ETC1
- graphics.TEXTURE_FORMAT_R_ETC2
- graphics.TEXTURE_FORMAT_RG_ETC2
- graphics.TEXTURE_FORMAT_RGBA_ETC2
- graphics.TEXTURE_FORMAT_RGBA_ASTC_4X4
- graphics.TEXTURE_FORMAT_RGB_BC1
- graphics.TEXTURE_FORMAT_RGBA_BC3
- graphics.TEXTURE_FORMAT_R_BC4
- graphics.TEXTURE_FORMAT_RG_BC5
- graphics.TEXTURE_FORMAT_RGBA_BC7
- graphics.TEXTURE_FORMAT_RGB16F
- graphics.TEXTURE_FORMAT_RGB32F
- graphics.TEXTURE_FORMAT_RGBA16F
- graphics.TEXTURE_FORMAT_RGBA32F
- graphics.TEXTURE_FORMAT_R16F
- graphics.TEXTURE_FORMAT_RG16F
- graphics.TEXTURE_FORMAT_R32F
- graphics.TEXTURE_FORMAT_RG32F
- graphics.TEXTURE_FORMAT_RGBA32UI
- graphics.TEXTURE_FORMAT_BGRA8U
- graphics.TEXTURE_FORMAT_R32UI

### gui

- gui.get_node(id: string | Hash): Opaque<"node">
- gui.get_id(node: Opaque<"node">): Hash
- gui.get_type(node: Opaque<"node">): Opaque<"constant">, number | nil
- gui.set_id(node: Opaque<"node">, id: string | Hash)
- gui.get(node: Opaque<"node">, property: string | Hash | Opaque<"constant">, options?: Record<string | number, unknown>)
- gui.set(node: Opaque<"node"> | Url, property: string | Hash | Opaque<"constant">, value: number | Vector4 | Vector3 | Quaternion, options?: Record<string | number, unknown>)
- gui.get_index(node: Opaque<"node">): number
- gui.delete_node(node: Opaque<"node">)
- gui.animate(node: Opaque<"node">, property: string | Opaque<"constant">, to: number | Vector3 | Vector4 | Quaternion, easing: Opaque<"constant"> | Vector, duration: number, delay?: number, complete_function?: function(self, node), playback?: Opaque<"constant">)
- gui.cancel_animations(node: Opaque<"node">, property?: nil | string | Opaque<"constant">)
- gui.new_box_node(pos: Vector3 | Vector4, size: Vector3): Opaque<"node">
- gui.new_text_node(pos: Vector3 | Vector4, text: string): Opaque<"node">
- gui.new_pie_node(pos: Vector3 | Vector4, size: Vector3): Opaque<"node">
- gui.get_text(node: Opaque<"node">): string
- gui.set_text(node: Opaque<"node">, text: string | number)
- gui.get_line_break(node: Opaque<"node">): boolean
- gui.set_line_break(node: Opaque<"node">, line_break: boolean)
- gui.get_blend_mode(node: Opaque<"node">): Opaque<"constant">
- gui.set_blend_mode(node: Opaque<"node">, blend_mode: Opaque<"constant">)
- gui.get_texture(node: Opaque<"node">): Hash
- gui.set_texture(node: Opaque<"node">, texture: string | Hash)
- gui.get_flipbook(node: Opaque<"node">): Hash
- gui.play_flipbook(node: Opaque<"node">, animation: string | Hash, complete_function?: function(self, node), play_properties?: Record<string | number, unknown>)
- gui.cancel_flipbook(node: Opaque<"node">)
- gui.new_texture(texture_id: string | Hash, width: number, height: number, type: string | Opaque<"constant">, buffer: string, flip: boolean): boolean, number
- gui.delete_texture(texture: string | Hash)
- gui.set_texture_data(texture: string | Hash, width: number, height: number, type: string | Opaque<"constant">, buffer: string, flip: boolean): boolean
- gui.get_material(node: Opaque<"node">): Hash
- gui.set_material(node: Opaque<"node">, material: string | Hash)
- gui.reset_material(node: Opaque<"node">)
- gui.get_font(node: Opaque<"node">): Hash
- gui.get_font_resource(font_name: Hash | string): Hash
- gui.set_font(node: Opaque<"node">, font: string | Hash)
- gui.get_layer(node: Opaque<"node">): Hash
- gui.set_layer(node: Opaque<"node">, layer: string | Hash)
- gui.get_layout(): Hash
- gui.set_layout(layout: string | Hash): boolean
- gui.get_layouts(): Record<string | number, unknown>
- gui.get_clipping_mode(node: Opaque<"node">): Opaque<"constant">
- gui.set_clipping_mode(node: Opaque<"node">, clipping_mode: Opaque<"constant">)
- gui.get_clipping_visible(node: Opaque<"node">): boolean
- gui.set_clipping_visible(node: Opaque<"node">, visible: boolean)
- gui.get_clipping_inverted(node: Opaque<"node">): boolean
- gui.set_clipping_inverted(node: Opaque<"node">, inverted: boolean)
- gui.get_xanchor(node: Opaque<"node">): Opaque<"constant">
- gui.set_xanchor(node: Opaque<"node">, anchor: Opaque<"constant">)
- gui.get_yanchor(node: Opaque<"node">): Opaque<"constant">
- gui.set_yanchor(node: Opaque<"node">, anchor: Opaque<"constant">)
- gui.get_pivot(node: Opaque<"node">): Opaque<"constant">
- gui.set_pivot(node: Opaque<"node">, pivot: Opaque<"constant">)
- gui.get_width(): number
- gui.get_height(): number
- gui.set_slice9(node: Opaque<"node">, values: Vector4)
- gui.get_slice9(node: Opaque<"node">): Vector4
- gui.set_perimeter_vertices(node: Opaque<"node">, vertices: number)
- gui.get_perimeter_vertices(node: Opaque<"node">): number
- gui.set_fill_angle(node: Opaque<"node">, angle: number)
- gui.get_fill_angle(node: Opaque<"node">): number
- gui.set_inner_radius(node: Opaque<"node">, radius: number)
- gui.get_inner_radius(node: Opaque<"node">): number
- gui.set_outer_bounds(node: Opaque<"node">, bounds_mode: Opaque<"constant">)
- gui.get_outer_bounds(node: Opaque<"node">): Opaque<"constant">
- gui.set_leading(node: Opaque<"node">, leading: number)
- gui.get_leading(node: Opaque<"node">): number
- gui.set_tracking(node: Opaque<"node">, tracking: number)
- gui.get_tracking(node: Opaque<"node">): number
- gui.pick_node(node: Opaque<"node">, x: number, y: number): boolean
- gui.is_enabled(node: Opaque<"node">, recursive?: boolean): boolean
- gui.set_enabled(node: Opaque<"node">, enabled: boolean)
- gui.get_visible(node: Opaque<"node">): boolean
- gui.set_visible(node: Opaque<"node">, visible: boolean)
- gui.get_adjust_mode(node: Opaque<"node">): Opaque<"constant">
- gui.set_adjust_mode(node: Opaque<"node">, adjust_mode: Opaque<"constant">)
- gui.set_safe_area_mode(mode: Opaque<"constant">)
- gui.get_size_mode(node: Opaque<"node">): Opaque<"constant">
- gui.set_size_mode(node: Opaque<"node">, size_mode: Opaque<"constant">)
- gui.move_above(node: Opaque<"node">, reference: Opaque<"node"> | nil)
- gui.move_below(node: Opaque<"node">, reference: Opaque<"node"> | nil)
- gui.get_parent(node: Opaque<"node">): Opaque<"node"> | nil
- gui.set_parent(node: Opaque<"node">, parent?: Opaque<"node">, keep_scene_transform?: boolean)
- gui.clone(node: Opaque<"node">): Opaque<"node">
- gui.clone_tree(node: Opaque<"node">): Record<string | number, unknown>
- gui.get_tree(node: Opaque<"node">): Record<string | number, unknown>
- gui.reset_nodes()
- gui.set_render_order(order: number)
- gui.show_keyboard(type: Opaque<"constant">, autoclose: boolean)
- gui.hide_keyboard()
- gui.reset_keyboard()
- gui.get_position(node: Opaque<"node">): Vector3
- gui.set_position(node: Opaque<"node">, position: Vector3 | Vector4)
- gui.get_rotation(node: Opaque<"node">): Quaternion
- gui.set_rotation(node: Opaque<"node">, rotation: Quaternion | Vector4)
- gui.get_euler(node: Opaque<"node">): Vector3
- gui.set_euler(node: Opaque<"node">, rotation: Vector3 | Vector4)
- gui.get_scale(node: Opaque<"node">): Vector3
- gui.set_scale(node: Opaque<"node">, scale: Vector3 | Vector4)
- gui.get_color(node: Opaque<"node">): Vector4
- gui.set_color(node: Opaque<"node">, color: Vector3 | Vector4)
- gui.get_outline(node: Opaque<"node">): Vector4
- gui.set_outline(node: Opaque<"node">, color: Vector3 | Vector4)
- gui.get_shadow(node: Opaque<"node">): Vector4
- gui.set_shadow(node: Opaque<"node">, color: Vector3 | Vector4)
- gui.set_size(node: Opaque<"node">, size: Vector3 | Vector4)
- gui.get_size(node: Opaque<"node">): Vector3
- gui.get_screen_position(node: Opaque<"node">): Vector3
- gui.set_screen_position(node: Opaque<"node">, screen_position: Vector3)
- gui.screen_to_local(node: Opaque<"node">, screen_position: Vector3): Vector3
- gui.get_flipbook_cursor(node: Opaque<"node">): number
- gui.set_flipbook_cursor(node: Opaque<"node">, cursor: number)
- gui.get_flipbook_playback_rate(node: Opaque<"node">): number
- gui.set_flipbook_playback_rate(node: Opaque<"node">, playback_rate: number)
- gui.new_particlefx_node(pos: Vector3 | Vector4, particlefx: Hash | string): Opaque<"node">
- gui.play_particlefx(node: Opaque<"node">, emitter_state_function?: function(self, node, emitter, state))
- gui.stop_particlefx(node: Opaque<"node">, options?: Record<string | number, unknown>)
- gui.set_particlefx(node: Opaque<"node">, particlefx: Hash | string)
- gui.get_particlefx(node: Opaque<"node">): Hash
- gui.get_inherit_alpha(node: Opaque<"node">): boolean
- gui.set_inherit_alpha(node: Opaque<"node">, inherit_alpha: boolean)
- gui.get_alpha(node: Opaque<"node">): number
- gui.set_alpha(node: Opaque<"node">, alpha: number)
- init(self: Opaque<"userdata">)
- final(self: Opaque<"userdata">)
- update(self: Opaque<"userdata">, dt: number)
- on_message(self: Opaque<"userdata">, message_id: Hash, message: Record<string | number, unknown>)
- on_input(self: Opaque<"userdata">, action_id: Hash, action: Record<string | number, unknown>): boolean | nil
- on_reload(self: Opaque<"userdata">)
- gui.PLAYBACK_ONCE_FORWARD
- gui.PLAYBACK_ONCE_BACKWARD
- gui.PLAYBACK_ONCE_PINGPONG
- gui.PLAYBACK_LOOP_FORWARD
- gui.PLAYBACK_LOOP_BACKWARD
- gui.PLAYBACK_LOOP_PINGPONG
- gui.EASING_LINEAR
- gui.EASING_INQUAD
- gui.EASING_OUTQUAD
- gui.EASING_INOUTQUAD
- gui.EASING_OUTINQUAD
- gui.EASING_INCUBIC
- gui.EASING_OUTCUBIC
- gui.EASING_INOUTCUBIC
- gui.EASING_OUTINCUBIC
- gui.EASING_INQUART
- gui.EASING_OUTQUART
- gui.EASING_INOUTQUART
- gui.EASING_OUTINQUART
- gui.EASING_INQUINT
- gui.EASING_OUTQUINT
- gui.EASING_INOUTQUINT
- gui.EASING_OUTINQUINT
- gui.EASING_INSINE
- gui.EASING_OUTSINE
- gui.EASING_INOUTSINE
- gui.EASING_OUTINSINE
- gui.EASING_INEXPO
- gui.EASING_OUTEXPO
- gui.EASING_INOUTEXPO
- gui.EASING_OUTINEXPO
- gui.EASING_INCIRC
- gui.EASING_OUTCIRC
- gui.EASING_INOUTCIRC
- gui.EASING_OUTINCIRC
- gui.EASING_INELASTIC
- gui.EASING_OUTELASTIC
- gui.EASING_INOUTELASTIC
- gui.EASING_OUTINELASTIC
- gui.EASING_INBACK
- gui.EASING_OUTBACK
- gui.EASING_INOUTBACK
- gui.EASING_OUTINBACK
- gui.EASING_INBOUNCE
- gui.EASING_OUTBOUNCE
- gui.EASING_INOUTBOUNCE
- gui.EASING_OUTINBOUNCE
- gui.KEYBOARD_TYPE_DEFAULT
- gui.KEYBOARD_TYPE_NUMBER_PAD
- gui.KEYBOARD_TYPE_EMAIL
- gui.KEYBOARD_TYPE_PASSWORD
- gui.PROP_POSITION
- gui.PROP_ROTATION
- gui.PROP_EULER
- gui.PROP_SCALE
- gui.PROP_COLOR
- gui.PROP_OUTLINE
- gui.PROP_SHADOW
- gui.PROP_SIZE
- gui.PROP_FILL_ANGLE
- gui.PROP_INNER_RADIUS
- gui.PROP_LEADING
- gui.PROP_TRACKING
- gui.PROP_SLICE9
- gui.BLEND_ALPHA
- gui.BLEND_ADD
- gui.BLEND_ADD_ALPHA
- gui.BLEND_MULT
- gui.BLEND_SCREEN
- gui.CLIPPING_MODE_NONE
- gui.CLIPPING_MODE_STENCIL
- gui.ANCHOR_LEFT
- gui.ANCHOR_RIGHT
- gui.ANCHOR_TOP
- gui.ANCHOR_BOTTOM
- gui.ANCHOR_NONE
- gui.PIVOT_CENTER
- gui.PIVOT_N
- gui.PIVOT_NE
- gui.PIVOT_E
- gui.PIVOT_SE
- gui.PIVOT_S
- gui.PIVOT_SW
- gui.PIVOT_W
- gui.PIVOT_NW
- gui.TYPE_BOX
- gui.TYPE_TEXT
- gui.TYPE_PIE
- gui.TYPE_PARTICLEFX
- gui.TYPE_CUSTOM
- gui.ADJUST_FIT
- gui.ADJUST_ZOOM
- gui.ADJUST_STRETCH
- gui.SAFE_AREA_NONE
- gui.SAFE_AREA_LONG
- gui.SAFE_AREA_SHORT
- gui.SAFE_AREA_BOTH
- gui.PIEBOUNDS_ELLIPSE
- gui.PIEBOUNDS_RECTANGLE
- gui.SIZE_MODE_MANUAL
- gui.SIZE_MODE_AUTO
- gui.RESULT_TEXTURE_ALREADY_EXISTS
- gui.RESULT_OUT_OF_RESOURCES
- gui.RESULT_DATA_ERROR
- material: Hash
- materials: Hash
- textures: Hash
- fonts: Hash

### html5

- html5.run(code: string): string
- html5.set_interaction_listener(callback: function(self) | nil)

### http

- http.request(url: string, method: string, callback: function(self, id, response), headers?: Record<string | number, unknown>, post_data?: string, options?: Record<string | number, unknown>)

### iac

- iac.set_listener(payload: Record<string | number, unknown>, type: number)

### iap

- iap.buy(id: string, options: Record<string | number, unknown>)
- iap.finish(transaction: Record<string | number, unknown>)
- iap.acknowledge(transaction: Record<string | number, unknown>)
- iap.get_provider_id(): Opaque<"constant">
- iap.list(ids: Record<string | number, unknown>, callback: (...args: unknown[]) => unknown)
- iap.restore(): boolean
- iap.set_listener(listener: (...args: unknown[]) => unknown)

### image

- image.load(buffer: string, options?: Record<string | number, unknown>): Record<string | number, unknown> | nil
- image.load_buffer(buffer: string, options?: Record<string | number, unknown>): Record<string | number, unknown> | nil
- image.get_astc_header(buffer: string): Record<string | number, unknown> | nil
- image.TYPE_RGB
- image.TYPE_RGBA
- image.TYPE_LUMINANCE
- image.TYPE_LUMINANCE_ALPHA

### json

- json.decode(json: string, options?: Record<string | number, unknown>): Record<string | number, unknown>
- json.encode(tbl: Record<string | number, unknown>, options?: Record<string | number, unknown>): string
- json.null: unknown

### label

- label.set_text(url: string | Hash | Url, text: string | number)
- label.get_text(url: string | Hash | Url): string
- color: Vector4
- outline: Vector4
- shadow: Vector4
- scale: number | Vector3
- size: Vector3
- material: Hash
- font: Hash
- leading: number
- tracking: number
- line_break: boolean

### liveupdate

- liveupdate.get_mounts(): Record<string | number, unknown>
- liveupdate.add_mount(name: string, uri: string, priority: number, callback: (...args: unknown[]) => unknown): number
- liveupdate.remove_mount(name: string): number
- liveupdate.LIVEUPDATE_OK
- liveupdate.LIVEUPDATE_INVALID_HEADER
- liveupdate.LIVEUPDATE_MEM_ERROR
- liveupdate.LIVEUPDATE_INVALID_RESOURCE
- liveupdate.LIVEUPDATE_VERSION_MISMATCH
- liveupdate.LIVEUPDATE_ENGINE_VERSION_MISMATCH
- liveupdate.LIVEUPDATE_SIGNATURE_MISMATCH
- liveupdate.LIVEUPDATE_SCHEME_MISMATCH
- liveupdate.LIVEUPDATE_BUNDLED_RESOURCE_MISMATCH
- liveupdate.LIVEUPDATE_FORMAT_ERROR
- liveupdate.LIVEUPDATE_IO_ERROR
- liveupdate.LIVEUPDATE_INVAL
- liveupdate.LIVEUPDATE_UNKNOWN

### model

- model.play_anim(url: string | Hash | Url, anim_id: string | Hash, playback: Opaque<"constant">, play_properties?: Record<string | number, unknown>, complete_function?: function(self, message_id, message, sender))
- model.cancel(url: string | Hash | Url)
- model.get_go(url: string | Hash | Url, bone_id: string | Hash): Hash
- model.set_mesh_enabled(url: string | Hash | Url, mesh_id: string | Hash | Url, enabled: boolean)
- model.get_mesh_enabled(url: string | Hash | Url, mesh_id: string | Hash | Url): boolean
- model.get_aabb(url: string | Hash | Url): Record<string | number, unknown>
- model.get_mesh_aabb(url: string | Hash | Url): Record<string | number, unknown>
- cursor: number
- playback_rate: number
- animation: Hash
- textureN: Hash
- material: Hash

### msg

- msg.url(): Url
- msg.url(urlstring: string): Url
- msg.url(socket?: string | Hash, path?: string | Hash, fragment?: string | Hash): Url
- msg.post(receiver: string | Url | Hash, message_id: string | Hash, message?: Record<string | number, unknown> | nil)

### particlefx

- particlefx.play(url: string | Hash | Url, emitter_state_function?: function(self, id, emitter, state))
- particlefx.stop(url: string | Hash | Url, options?: Record<string | number, unknown>)
- particlefx.set_constant(url: string | Hash | Url, emitter: string | Hash, constant: string | Hash, value: Vector4)
- particlefx.reset_constant(url: string | Hash | Url, emitter: string | Hash, constant: string | Hash)
- particlefx.EMITTER_STATE_SLEEPING
- particlefx.EMITTER_STATE_PRESPAWN
- particlefx.EMITTER_STATE_SPAWNING
- particlefx.EMITTER_STATE_POSTSPAWN
- material: Hash
- image: Hash
- animation: Hash

### physics

- physics.raycast_async(from: Vector3, to: Vector3, groups: Record<string | number, unknown>, request_id?: number)
- physics.raycast(from: Vector3, to: Vector3, groups: Record<string | number, unknown>, options?: Record<string | number, unknown>): Record<string | number, unknown> | nil
- physics.create_joint(joint_type: number, collisionobject_a: string | Hash | Url, joint_id: string | Hash, position_a: Vector3, collisionobject_b: string | Hash | Url, position_b: Vector3, properties?: Record<string | number, unknown>)
- physics.destroy_joint(collisionobject: string | Hash | Url, joint_id: string | Hash)
- physics.get_joint_properties(collisionobject: string | Hash | Url, joint_id: string | Hash): Record<string | number, unknown>
- physics.set_joint_properties(collisionobject: string | Hash | Url, joint_id: string | Hash, properties: Record<string | number, unknown>)
- physics.get_joint_reaction_force(collisionobject: string | Hash | Url, joint_id: string | Hash): Vector3
- physics.get_joint_reaction_torque(collisionobject: string | Hash | Url, joint_id: string | Hash): number
- physics.set_gravity(gravity: Vector3)
- physics.get_gravity(): Vector3
- physics.set_hflip(url: string | Hash | Url, flip: boolean)
- physics.set_vflip(url: string | Hash | Url, flip: boolean)
- physics.wakeup(url: string | Hash | Url)
- physics.set_group(url: string | Hash | Url, group: string)
- physics.get_group(url: string | Hash | Url): Hash
- physics.set_maskbit(url: string | Hash | Url, group: string, maskbit: boolean)
- physics.get_maskbit(url: string | Hash | Url, group: string): boolean
- physics.get_shape(url: string | Hash | Url, shape: string | Hash): Record<string | number, unknown>
- physics.set_shape(url: string | Hash | Url, shape: string | Hash, table: Record<string | number, unknown>)
- physics.set_event_listener(callback: function(self, events) | nil)
- physics.update_mass(collisionobject: string | Hash | Url, mass: number)
- physics.JOINT_TYPE_SPRING
- physics.JOINT_TYPE_FIXED
- physics.JOINT_TYPE_HINGE
- physics.JOINT_TYPE_SLIDER
- physics.JOINT_TYPE_WELD
- physics.JOINT_TYPE_WHEEL
- physics.SHAPE_TYPE_SPHERE
- physics.SHAPE_TYPE_BOX
- physics.SHAPE_TYPE_CAPSULE
- physics.SHAPE_TYPE_HULL
- mass: number
- linear_velocity: Vector3
- angular_velocity: Vector3
- linear_damping: number
- angular_damping: number

### profiler

- profiler.get_memory_usage(): number
- profiler.get_cpu_usage(): number
- profiler.enable(enabled: boolean)
- profiler.enable_ui(enabled: boolean)
- profiler.set_ui_mode(mode: Opaque<"constant">)
- profiler.set_ui_view_mode(mode: Opaque<"constant">)
- profiler.set_ui_vsync_wait_visible(visible: boolean)
- profiler.recorded_frame_count(): number
- profiler.view_recorded_frame(frame_index: Record<string | number, unknown>)
- profiler.log_text(text: string)
- profiler.dump_frame()
- profiler.scope_begin(name: string)
- profiler.scope_end()
- profiler.MODE_RUN
- profiler.MODE_PAUSE
- profiler.MODE_SHOW_PEAK_FRAME
- profiler.MODE_RECORD
- profiler.VIEW_MODE_FULL
- profiler.VIEW_MODE_MINIMIZED

### push

- push.register(notifications: Record<string | number, unknown>, callback: (...args: unknown[]) => unknown)
- push.set_listener(listener: (...args: unknown[]) => unknown)
- push.set_badge_count(count: number)
- push.schedule(time: number, title: string, alert: string, payload: string, notification_settings: Record<string | number, unknown>): number, string
- push.cancel(id: number)
- push.cancel_all_issued()
- push.get_scheduled(id: number): Record<string | number, unknown>
- push.get_all_scheduled(): Record<string | number, unknown>

### render

- render.constant_buffer(): Opaque<"constant_buffer">
- render.enable_state(state: Opaque<"constant">)
- render.disable_state(state: Opaque<"constant">)
- render.set_viewport(x: number, y: number, width: number, height: number)
- render.render_target(name: string, parameters: Record<string | number, unknown>): Opaque<"render_target">
- render.delete_render_target(render_target: Opaque<"render_target">)
- render.set_render_target(render_target: Opaque<"render_target">, options?: Record<string | number, unknown>)
- render.set_render_target_size(render_target: Opaque<"render_target">, width: number, height: number)
- render.enable_texture(binding: number | string | Hash, handle_or_name: Opaque<"texture"> | string | Hash, buffer_type?: graphics.BUFFER_TYPE_COLOR0_BIT | graphics.BUFFER_TYPE_COLOR1_BIT | graphics.BUFFER_TYPE_COLOR2_BIT | graphics.BUFFER_TYPE_COLOR3_BIT | graphics.BUFFER_TYPE_DEPTH_BIT | graphics.BUFFER_TYPE_STENCIL_BIT)
- render.disable_texture(binding: Opaque<"texture"> | string | Hash)
- render.get_render_target_width(render_target: Opaque<"render_target">, buffer_type: graphics.BUFFER_TYPE_COLOR0_BIT | graphics.BUFFER_TYPE_COLOR1_BIT | graphics.BUFFER_TYPE_COLOR2_BIT | graphics.BUFFER_TYPE_COLOR3_BIT | graphics.BUFFER_TYPE_DEPTH_BIT | graphics.BUFFER_TYPE_STENCIL_BIT): number
- render.get_render_target_height(render_target: Opaque<"render_target">, buffer_type: graphics.BUFFER_TYPE_COLOR0_BIT | graphics.BUFFER_TYPE_COLOR1_BIT | graphics.BUFFER_TYPE_COLOR2_BIT | graphics.BUFFER_TYPE_COLOR3_BIT | graphics.BUFFER_TYPE_DEPTH_BIT | graphics.BUFFER_TYPE_STENCIL_BIT): number
- render.clear(buffers: Record<string | number, unknown>)
- render.draw(predicate: number, options?: Record<string | number, unknown>)
- render.draw_debug3d(options?: Record<string | number, unknown>)
- render.set_view(matrix: Matrix4)
- render.set_projection(matrix: Matrix4)
- render.set_blend_func(source_factor: number, destination_factor: number)
- render.set_color_mask(red: boolean, green: boolean, blue: boolean, alpha: boolean)
- render.set_depth_mask(depth: boolean)
- render.set_stencil_mask(mask: number)
- render.set_depth_func(func: number)
- render.set_stencil_func(func: number, ref: number, mask: number)
- render.set_stencil_op(sfail: number, dpfail: number, dppass: number)
- render.set_cull_face(face_type: number)
- render.set_polygon_offset(factor: number, units: number)
- render.get_width(): number
- render.get_height(): number
- render.get_window_width(): number
- render.get_window_height(): number
- render.predicate(tags: Record<string | number, unknown>): number
- render.enable_material(material_id: string | Hash)
- render.disable_material()
- render.set_camera(camera: Url | number | nil, options?: Record<string | number, unknown>)
- render.set_compute(compute: string | Hash | nil)
- render.dispatch_compute(x: number, y: number, z: number, options?: Record<string | number, unknown>)
- render.set_listener(callback: function(self, event_type) | nil)
- render.RENDER_TARGET_DEFAULT
- render.FRUSTUM_PLANES_SIDES
- render.FRUSTUM_PLANES_ALL
- render.SORT_BACK_TO_FRONT
- render.SORT_FRONT_TO_BACK
- render.SORT_NONE

### resource

- resource.material(path?: string): Hash
- resource.font(path?: string): Hash
- resource.texture(path?: string): Hash
- resource.atlas(path?: string): Hash
- resource.buffer(path?: string): Hash
- resource.tile_source(path?: string): Hash
- resource.render_target(path?: string): Hash
- resource.set(path: string | Hash, buffer: Opaque<"buffer">)
- resource.load(path: string): Opaque<"buffer">
- resource.create_texture(path: string, table: Record<string | number, unknown>, buffer: Opaque<"buffer">): Hash
- resource.create_texture_async(path: string | Hash, table: Record<string | number, unknown>, buffer: Opaque<"buffer">, callback: (...args: unknown[]) => unknown): Hash, number
- resource.release(path: Hash | string)
- resource.set_texture(path: Hash | string, table: Record<string | number, unknown>, buffer: Opaque<"buffer">)
- resource.get_texture_info(path: Hash | string | number): Record<string | number, unknown>
- resource.get_render_target_info(path: Hash | string | number): Record<string | number, unknown>
- resource.create_atlas(path: string, table: Record<string | number, unknown>): Hash
- resource.set_atlas(path: Hash | string, table: Record<string | number, unknown>)
- resource.get_atlas(path: Hash | string): Record<string | number, unknown>
- resource.set_sound(path: Hash | string, buffer: string)
- resource.create_sound_data(path: string, options?: Record<string | number, unknown>): Hash
- resource.create_buffer(path: string, table?: Record<string | number, unknown>): Hash
- resource.get_buffer(path: Hash | string): Opaque<"buffer">
- resource.set_buffer(path: Hash | string, buffer: Opaque<"buffer">, table?: Record<string | number, unknown>)
- resource.get_text_metrics(url: Hash, text: string, options?: Record<string | number, unknown>): Record<string | number, unknown>

### socket

- socket.select(recvt: (client | master | unconnected)[], sendt: (client | master | unconnected)[], timeout?: number): LuaMultiReturn<[(client | master | unconnected)[], (client | master | unconnected)[], string | unknown]>
- socket.tcp6(): LuaMultiReturn<[master | unknown, string | unknown]>
- socket.udp6(): LuaMultiReturn<[unconnected | unknown, string | unknown]>
- socket.dns.tohostname(address: string): LuaMultiReturn<[string | unknown, Record<string | number, unknown> | string]>
- socket.dns.toip(address: string): LuaMultiReturn<[string | unknown, Record<string | number, unknown> | string]>
- socket.dns.gethostname(): string
- socket.dns.getaddrinfo(address: string): LuaMultiReturn<[Record<string | number, unknown> | unknown, string | unknown]>
- socket.dns.getnameinfo(address: string): LuaMultiReturn<[Record<string | number, unknown> | unknown, string | unknown]>
- socket.connect(address: string, port: number, locaddr?: string, locport?: number, family?: string): LuaMultiReturn<[client | unknown, string | unknown]>
- socket.udp(): LuaMultiReturn<[unconnected | unknown, string | unknown]>
- socket.skip(d: number, ret1?: unknown, ret2?: unknown, retN?: unknown): LuaMultiReturn<[unknown, unknown, unknown]>
- socket.tcp(): LuaMultiReturn<[master | unknown, string | unknown]>
- socket.newtry(finalizer: () => void): (...args: unknown[]) => unknown
- socket.protect(func: (...args: unknown[]) => unknown): (arg0: unknown) => void
- socket.gettime(): number
- socket.sleep(time: number): void
- server:accept(): LuaMultiReturn<[client | unknown, string | unknown]>
- master:bind(address: string, port: number): LuaMultiReturn<[number | unknown, string | unknown]>
- master:close(): void
- client:close(): void
- server:close(): void
- master:connect(address: string, port: number): LuaMultiReturn<[number | unknown, string | unknown]>
- client:getpeername(): string
- master:getsockname(): string
- client:getsockname(): string
- server:getsockname(): string
- master:getstats(): string
- client:getstats(): string
- server:getstats(): string
- master:listen(backlog: number): LuaMultiReturn<[number | unknown, string | unknown]>
- client:receive(pattern?: string | number, prefix?: string): LuaMultiReturn<[string | unknown, string | unknown, string | unknown]>
- client:send(data: string, i?: number, j?: number): LuaMultiReturn<[number | unknown, string | unknown, number | unknown]>
- client:setoption(option: string, value?: unknown): LuaMultiReturn<[number | unknown, string | unknown]>
- server:setoption(option: string, value?: unknown): LuaMultiReturn<[number | unknown, string | unknown]>
- client:getoption(option: string): LuaMultiReturn<[unknown, string | unknown]>
- server:getoption(option: string): LuaMultiReturn<[unknown, string | unknown]>
- master:setstats(received: number, sent: number, age: number): number | unknown
- client:setstats(received: number, sent: number, age: number): number | unknown
- server:setstats(received: number, sent: number, age: number): number | unknown
- master:settimeout(value: number, mode?: string): void
- client:settimeout(value: number, mode?: string): void
- server:settimeout(value: number, mode?: string): void
- client:shutdown(mode: string): number
- master:dirty(): boolean
- client:dirty(): boolean
- server:dirty(): boolean
- master:getfd(): number
- client:getfd(): number
- server:getfd(): number
- master:setfd(handle: number): void
- client:setfd(handle: number): void
- server:setfd(handle: number): void
- connected:close(): void
- unconnected:close(): void
- connected:getpeername(): string
- connected:getsockname(): string
- unconnected:getsockname(): string
- connected:receive(size?: number): LuaMultiReturn<[string | unknown, string | unknown]>
- unconnected:receive(size?: number): LuaMultiReturn<[string | unknown, string | unknown]>
- unconnected:receivefrom(size?: number): LuaMultiReturn<[string | unknown, string, number | unknown]>
- connected:getoption(option: string): LuaMultiReturn<[unknown, string | unknown]>
- unconnected:getoption(option: string): LuaMultiReturn<[unknown, string | unknown]>
- connected:send(datagram: string): LuaMultiReturn<[number | unknown, string | unknown]>
- unconnected:sendto(datagram: string, ip: string, port: number): LuaMultiReturn<[number | unknown, string | unknown]>
- connected:setpeername(arg0: string): LuaMultiReturn<[number | unknown, string | unknown]>
- unconnected:setpeername(address: string, port: number): LuaMultiReturn<[number | unknown, string | unknown]>
- unconnected:setsockname(address: string, port: number): LuaMultiReturn<[number | unknown, string | unknown]>
- connected:setoption(option: string, value?: unknown): LuaMultiReturn<[number | unknown, string | unknown]>
- unconnected:setoption(option: string, value?: unknown): LuaMultiReturn<[number | unknown, string | unknown]>
- connected:settimeout(value: number): void
- unconnected:settimeout(value: number): void
- socket._VERSION
- socket._SETSIZE

### sound

- sound.is_music_playing(): boolean
- sound.get_rms(group: string | Hash, window: number): number, number
- sound.get_peak(group: string | Hash, window: number): number, number
- sound.set_group_gain(group: string | Hash, gain: number)
- sound.get_group_gain(group: string | Hash): number
- sound.get_groups(): Record<string | number, unknown>
- sound.get_group_name(group: string | Hash): string
- sound.is_phone_call_active(): boolean
- sound.play(url: string | Hash | Url, play_properties?: Record<string | number, unknown>, complete_function?: function(self, message_id, message, sender)): number
- sound.stop(url: string | Hash | Url, stop_properties?: Record<string | number, unknown>)
- sound.pause(url: string | Hash | Url, pause: boolean)
- sound.set_gain(url: string | Hash | Url, gain?: number)
- sound.set_pan(url: string | Hash | Url, pan?: number)
- gain: number
- pan: number
- speed: number
- sound: Hash

### sprite

- sprite.set_hflip(url: string | Hash | Url, flip: boolean)
- sprite.set_vflip(url: string | Hash | Url, flip: boolean)
- sprite.play_flipbook(url: string | Hash | Url, id: string | Hash, complete_function?: function(self, message_id, message, sender), play_properties?: Record<string | number, unknown>)
- size: Vector3
- slice: Vector4
- scale: Vector3
- image: Hash
- material: Hash
- cursor: number
- playback_rate: number
- animation: Hash
- frame_count: Hash

### sys

- sys.save(filename: string, table: Record<string | number, unknown>)
- sys.load(filename: string): Record<string | number, unknown>
- sys.exists(path: string): boolean
- sys.get_host_path(filename: string): string
- sys.get_save_file(application_id: string, file_name: string): string
- sys.get_application_path(): string
- sys.get_config_string(key: string, default_value?: string): string
- sys.get_config_int(key: string, default_value?: number): number
- sys.get_config_number(key: string, default_value?: number): number
- sys.get_config_boolean(key: string, default_value?: boolean): boolean
- sys.open_url(url: string, attributes?: Record<string | number, unknown>): boolean
- sys.load_resource(filename: string): string | nil, string | nil
- sys.get_sys_info(options?: Record<string | number, unknown>): Record<string | number, unknown>
- sys.get_engine_info(): Record<string | number, unknown>
- sys.get_application_info(app_string: string): Record<string | number, unknown>
- sys.get_ifaddrs(): Record<string | number, unknown>
- sys.set_error_handler(error_handler: function(source, message, traceback))
- sys.set_connectivity_host(host: string)
- sys.get_connectivity(): Opaque<"constant">
- sys.exit(code: number)
- sys.reboot(arg1?: string, arg2?: string, arg3?: string, arg4?: string, arg5?: string, arg6?: string)
- sys.set_vsync_swap_interval(swap_interval: number)
- sys.set_update_frequency(frequency: number)
- sys.serialize(table: Record<string | number, unknown>): string
- sys.deserialize(buffer: string): Record<string | number, unknown>
- sys.load_buffer(path: string): Opaque<"buffer">
- sys.load_buffer_async(path: string, status_callback: function(self, request_id, result)): number
- sys.set_engine_throttle(enable: boolean, cooldown: number)
- sys.set_render_enable(enable: boolean)
- sys.NETWORK_DISCONNECTED
- sys.NETWORK_CONNECTED_CELLULAR
- sys.NETWORK_CONNECTED
- sys.REQUEST_STATUS_FINISHED
- sys.REQUEST_STATUS_ERROR_IO_ERROR
- sys.REQUEST_STATUS_ERROR_NOT_FOUND

### tilemap

- tilemap.set_tile(url: string | Hash | Url, layer: string | Hash, x: number, y: number, tile: number, transform_bitmask?: number)
- tilemap.get_tile(url: string | Hash | Url, layer: string | Hash, x: number, y: number): number
- tilemap.get_tile_info(url: string | Hash | Url, layer: string | Hash, x: number, y: number): Record<string | number, unknown>
- tilemap.get_tiles(url: string | Hash | Url, layer: string | Hash): Record<string | number, unknown>
- tilemap.get_bounds(url: string | Hash | Url): number, number, number, number
- tilemap.set_visible(url: string | Hash | Url, layer: string | Hash, visible: boolean)
- tilemap.H_FLIP
- tilemap.V_FLIP
- tilemap.ROTATE_90
- tilemap.ROTATE_180
- tilemap.ROTATE_270
- tile_source: Hash
- material: Hash

### timer

- timer.delay(delay: number, repeating: boolean, callback: function(self, handle, time_elapsed)): number
- timer.cancel(handle: number): boolean
- timer.trigger(handle: number): boolean
- timer.get_info(handle: number): Record<string | number, unknown> | nil
- timer.INVALID_TIMER_HANDLE

### types

- types.is_vector(var: unknown): boolean
- types.is_matrix4(var: unknown): boolean
- types.is_vector3(var: unknown): boolean
- types.is_vector4(var: unknown): boolean
- types.is_quat(var: unknown): boolean
- types.is_hash(var: unknown): boolean
- types.is_url(var: unknown): boolean

### vmath

- vmath.vector(t: Record<string | number, unknown>): Vector
- vmath.vector3(): Vector3
- vmath.vector3(n: number): Vector3
- vmath.vector3(v1: Vector3): Vector3
- vmath.vector3(x: number, y: number, z: number): Vector3
- vmath.vector4(): Vector4
- vmath.vector4(n: number): Vector4
- vmath.vector4(v1: Vector4): Vector4
- vmath.vector4(x: number, y: number, z: number, w: number): Vector4
- vmath.quat(): Quaternion
- vmath.quat(q1: Quaternion): Quaternion
- vmath.quat(x: number, y: number, z: number, w: number): Quaternion
- vmath.quat_from_to(v1: Vector3, v2: Vector3): Quaternion
- vmath.quat_axis_angle(v: Vector3, angle: number): Quaternion
- vmath.quat_basis(x: Vector3, y: Vector3, z: Vector3): Quaternion
- vmath.quat_rotation_x(angle: number): Quaternion
- vmath.quat_rotation_y(angle: number): Quaternion
- vmath.quat_rotation_z(angle: number): Quaternion
- vmath.matrix4(): Matrix4
- vmath.matrix4(m1: Matrix4): Matrix4
- vmath.matrix4_frustum(left: number, right: number, bottom: number, top: number, near: number, far: number): Matrix4
- vmath.matrix4_look_at(eye: Vector3, look_at: Vector3, up: Vector3): Matrix4
- vmath.matrix4_orthographic(left: number, right: number, bottom: number, top: number, near: number, far: number): Matrix4
- vmath.matrix4_perspective(fov: number, aspect: number, near: number, far: number): Matrix4
- vmath.matrix4_quat(q: Quaternion): Matrix4
- vmath.matrix4_axis_angle(v: Vector3, angle: number): Matrix4
- vmath.matrix4_rotation_x(angle: number): Matrix4
- vmath.matrix4_rotation_y(angle: number): Matrix4
- vmath.matrix4_rotation_z(angle: number): Matrix4
- vmath.matrix4_translation(position: Vector3 | Vector4): Matrix4
- vmath.inv(m1: Matrix4): Matrix4
- vmath.ortho_inv(m1: Matrix4): Matrix4
- vmath.dot(v1: Vector3 | Vector4, v2: Vector3 | Vector4): number
- vmath.length_sqr(v: Vector3 | Vector4 | Quaternion): number
- vmath.length(v: Vector3 | Vector4 | Quaternion): number
- vmath.normalize<T extends Vector3 | Vector4 | Quaternion>(v1: T): T
- vmath.cross(v1: Vector3, v2: Vector3): Vector3
- vmath.lerp<T extends Vector3 | Vector4>(t: number, v1: T, v2: T): T
- vmath.lerp(t: number, q1: Quaternion, q2: Quaternion): Quaternion
- vmath.lerp(t: number, n1: number, n2: number): number
- vmath.slerp<T extends Vector3 | Vector4>(t: number, v1: T, v2: T): T
- vmath.slerp(t: number, q1: Quaternion, q2: Quaternion): Quaternion
- vmath.conj(q1: Quaternion): Quaternion
- vmath.rotate(q: Quaternion, v1: Vector3): Vector3
- vmath.project(v1: Vector3, v2: Vector3): number
- vmath.mul_per_elem<T extends Vector3 | Vector4>(v1: T, v2: T): T
- vmath.quat_matrix4(matrix: Matrix4): Quaternion
- vmath.matrix4_compose(translation: Vector3 | Vector4, rotation: Quaternion, scale: Vector3): Matrix4
- vmath.matrix4_scale(scale: Vector3): Matrix4
- vmath.matrix4_scale(scale: number): Matrix4
- vmath.matrix4_scale(scale_x: number, scale_y: number, scale_z: number): Matrix4
- vmath.clamp<T extends number | Vector3 | Vector4>(value: T, min: number | T, max: number | T): T
- vmath.quat_to_euler(q: Quaternion): number, number, number
- vmath.euler_to_quat(x: number | Vector3, y: number, z: number): Quaternion

### webview

- webview.create(callback: (...args: unknown[]) => unknown)
- webview.destroy(webview_id: number)
- webview.open_raw(webview_id: number, html: string, options: Record<string | number, unknown>)
- webview.eval(webview_id: number, code: string)
- webview.set_transparent(webview_id: number, transparent: boolean)
- webview.set_visible(webview_id: number, visible: number)
- webview.is_visible(webview_id: number)
- webview.set_position(webview_id: number, x: number, y: number, width: number, height: number)

### window

- window.set_listener(callback: function(self, event, data) | nil)
- window.set_mouse_lock(flag: boolean)
- window.set_dim_mode(mode: Opaque<"constant">)
- window.get_dim_mode(): Opaque<"constant">
- window.get_size(): number, number
- window.get_safe_area(): Record<string | number, unknown>
- window.get_mouse_lock(): boolean
- window.get_display_scale(): number
- window.set_title(title: string)
- window.set_size(width: number, height: number)
- window.set_position(x: number, y: number)
- window.WINDOW_EVENT_FOCUS_LOST
- window.WINDOW_EVENT_FOCUS_GAINED
- window.WINDOW_EVENT_RESIZED
- window.WINDOW_EVENT_ICONFIED
- window.WINDOW_EVENT_DEICONIFIED
- window.DIMMING_ON
- window.DIMMING_OFF
- window.DIMMING_UNKNOWN

### zlib

- zlib.inflate(buf: string): string
- zlib.deflate(buf: string): string

### Hash


### Matrix4

- mul(rhs: Matrix4): Matrix4
- mul(rhs: Vector4): Vector4
- m00: number
- m01: number
- m02: number
- m03: number
- m10: number
- m11: number
- m12: number
- m13: number
- m20: number
- m21: number
- m22: number
- m23: number
- m30: number
- m31: number
- m32: number
- m33: number
- c0: Vector4
- c1: Vector4
- c2: Vector4
- c3: Vector4

### Opaque


### Quaternion

- mul(rhs: Quaternion): Quaternion
- x: number
- y: number
- z: number
- w: number

### Url

- socket: Hash
- path: Hash
- fragment: Hash | undefined

### Vector

- length: number

### Vector3

- add(rhs: Vector3): Vector3
- sub(rhs: Vector3): Vector3
- mul(rhs: number): Vector3
- div(rhs: number): Vector3
- unm(): Vector3
- x: number
- y: number
- z: number

### Vector4

- add(rhs: Vector4): Vector4
- sub(rhs: Vector4): Vector4
- mul(rhs: number): Vector4
- div(rhs: number): Vector4
- unm(): Vector4
- x: number
- y: number
- z: number
- w: number

### base

- assert<T>(v: T, message?: any): Exclude<T, undefined | null | false>
- collectgarbage(opt?: "collect" | "stop" | "restart" | "count" | "step" | "setpause" | "setstepmul", arg?: number): number
- dofile(filename?: string): any
- error(message: string, level?: number): never
- getfenv(f?: Function | number): any
- getmetatable<T>(object: T): LuaMetatable<T> | undefined
- ipairs<T>(t: Record<number, T>): LuaIterable<LuaMultiReturn<[number, NonNullable<T>]>>
- load(func: () => string | null | undefined, chunkname?: string): LuaMultiReturn<[() => any] | [undefined, string]>
- loadfile(filename?: string): LuaMultiReturn<[() => any] | [undefined, string]>
- loadstring(chunk: string | (() => string | null | undefined), chunkname?: string, mode?: "b" | "t" | "bt", env?: object): LuaMultiReturn<[() => any] | [undefined, string]>
- next(table: object, index?: any): LuaMultiReturn<[any, any] | []>
- pairs<T>(t: T): LuaIterable<LuaMultiReturn<[keyof T, NonNullable<T[keyof T]>]>>
- pcall<A extends any[], R>(f: (...args: A) => R, ...args: A): LuaMultiReturn<[true, R] | [false, string]>
- print(...args: any[]): void
- rawequal<T>(v1: T, v2: T): boolean
- rawget<T extends object, K extends keyof T>(table: T, index: K): T[K]
- rawset<T extends object, K extends keyof T>(table: T, index: K, value: T[K]): T
- select<T>(index: number, ...args: T[]): LuaMultiReturn<T[]>
- select<T>(index: "#", ...args: T[]): number
- setfenv<T extends Function>(f: T, table: object): T
- setmetatable<T extends object>(table: T, metatable?: LuaMetatable<T> | null): T
- tonumber(e: any, base?: number): number | undefined
- tostring(v: any): string
- type(v: any): "nil" | "number" | "string" | "boolean" | "table" | "function" | "thread" | "userdata"
- unpack<T extends any[]>(list: T): LuaMultiReturn<T>
- unpack<T>(list: T[], i: number, j?: number): LuaMultiReturn<T[]>
- xpcall<R, E>(f: () => R, err: (err: any) => E): LuaMultiReturn<[true, R] | [false, E]>
- module(name: string, ...options: any[]): void
- require(modname: string): any
- _G: unknown
- _VERSION: unknown

### bit

- bit.tobit(x: number): number
- bit.tohex(x: number, n?: number): string
- bit.bnot(x: number): number
- bit.bor(x: number, ...rest: number[]): number
- bit.band(x: number, ...rest: number[]): number
- bit.bxor(x: number, ...rest: number[]): number
- bit.lshift(x: number, n: number): number
- bit.rshift(x: number, n: number): number
- bit.arshift(x: number, n: number): number
- bit.rol(x: number, n: number): number
- bit.ror(x: number, n: number): number
- bit.bswap(x: number): number

### coroutine

- coroutine.create(f: (...args: any[]) => any): LuaThread
- coroutine.resume(co: LuaThread, ...val: any[]): LuaMultiReturn<[true, ...any[]] | [false, string]>
- coroutine.running(): LuaThread | undefined
- coroutine.status(co: LuaThread): "running" | "suspended" | "normal" | "dead"
- coroutine.wrap(f: (...args: any[]) => any): (...args: any[]) => LuaMultiReturn<any[]>
- coroutine.yield(...args: any[]): LuaMultiReturn<any[]>

### debug

- debug.debug(): void
- debug.getfenv(o: object): any
- debug.gethook(thread?: LuaThread): LuaMultiReturn<[undefined, 0] | [Function, number, string?]>
- debug.getinfo(f: Function | number, what?: string): FunctionInfo
- debug.getlocal(level: number, local: number): LuaMultiReturn<[string, any]>
- debug.getmetatable<T>(value: T): LuaMetatable<T> | undefined
- debug.getregistry(): Record<string, any>
- debug.getupvalue(f: Function, up: number): LuaMultiReturn<[string, any] | []>
- debug.setfenv<T extends object>(o: T, table: object): T
- debug.sethook(hook?: (event: "call" | "return" | "line" | "count", line?: number) => any, mask?: string, count?: number): void
- debug.setlocal(level: number, local: number, value: any): string | undefined
- debug.setmetatable<T extends object>(value: T, table?: LuaMetatable<T> | null): T
- debug.setupvalue(f: Function, up: number, value: any): string | undefined
- debug.traceback(message?: string, level?: number): string

### io

- io.close(file?: LuaFile): boolean
- io.flush(): boolean
- io.input(file?: string | LuaFile): LuaFile
- io.lines(filename?: string, ...formats: ("*n" | "*l" | "*a" | number)[]): LuaIterable<string | number>
- io.open(filename: string, mode?: string): LuaFile | undefined
- io.output(file?: string | LuaFile): LuaFile
- io.popen(prog: string, mode?: "r" | "w"): LuaFile | undefined
- io.read(): string | undefined
- io.read(format: "*n" | "*l" | "*a" | number): string | number | undefined
- io.read(...formats: ("*n" | "*l" | "*a" | number)[]): (string | number | undefined)[]
- io.tmpfile(): LuaFile
- io.type(obj: unknown): "file" | "closed file" | undefined
- io.write(...args: (string | number)[]): LuaFile | undefined
- file:close(): boolean
- file:flush(): boolean
- file:lines(): LuaIterable<string>
- file:lines(...formats: ("*n" | "*l" | "*a" | number)[]): LuaIterable<string | number>
- file:read(): string | undefined
- file:read(format: "*n" | "*l" | "*a" | number): string | number | undefined
- file:read(...formats: ("*n" | "*l" | "*a" | number)[]): (string | number | undefined)[]
- file:seek(whence?: "set" | "cur" | "end", offset?: number): number | undefined
- file:setvbuf(mode: "no" | "full" | "line", size?: number): void
- file:write(...args: (string | number)[]): LuaFile | undefined

### math

- math.abs(x: number): number
- math.acos(x: number): number
- math.asin(x: number): number
- math.atan(x: number): number
- math.atan2(y: number, x: number): number
- math.ceil(x: number): number
- math.cos(x: number): number
- math.cosh(x: number): number
- math.deg(x: number): number
- math.exp(x: number): number
- math.floor(x: number): number
- math.fmod(x: number, y: number): number
- math.frexp(x: number): LuaMultiReturn<[number, number]>
- math.ldexp(m: number, e: number): number
- math.log(x: number): number
- math.log10(x: number): number
- math.max(x: number, ...numbers: number[]): number
- math.min(x: number, ...numbers: number[]): number
- math.modf(x: number): LuaMultiReturn<[number, number]>
- math.pow(x: number, y: number): number
- math.rad(x: number): number
- math.random(m?: number, n?: number): number
- math.randomseed(x: number): number
- math.sin(x: number): number
- math.sinh(x: number): number
- math.sqrt(x: number): number
- math.tan(x: number): number
- math.tanh(x: number): number
- math.huge: unknown
- math.pi: unknown

### os

- os.clock(): number
- os.date(format?: string, time?: number): string
- os.date(format: "*t", time?: number): LuaDateInfoResult
- os.difftime(t1: number, t2: number): number
- os.execute(command?: string): number
- os.exit(code?: number): never
- os.getenv(varname: string): string | undefined
- os.remove(filename: string): LuaMultiReturn<[true] | [undefined, string]>
- os.rename(oldname: string, newname: string): LuaMultiReturn<[true] | [undefined, string]>
- os.setlocale(locale?: string, category?: "all" | "collate" | "ctype" | "monetary" | "numeric" | "time"): string | undefined
- os.time(): number
- os.time(table: LuaDateInfo): number
- os.tmpname(): string

### package

- package.cpath: string
- package.loaded: Record<string, any>
- package.loaders: (((modname: string) => LuaMultiReturn<[(modname: string) => void]>) | (<T>(modname: string) => LuaMultiReturn<[(modname: string, extra: T) => T, T]>) | string)[]
- package.loadlib(libname: string, funcname: string): [Function] | [undefined, string, "open" | "init"]
- package.path: string
- package.preload: Record<string, (modname: string, fileName?: string) => any>
- package.seeall(module: object): void

### string

- string.byte(s: string, i?: number): number
- string.byte(s: string, i?: number, j?: number): LuaMultiReturn<number[]>
- string.char(...args: number[]): string
- string.dump(func: Function): string
- string.find(s: string, pattern: string, init?: number, plain?: boolean): LuaMultiReturn<[number, number, ...string[]] | []>
- string.format(formatstring: string, ...args: any[]): string
- string.gmatch(s: string, pattern: string): LuaIterable<LuaMultiReturn<string[]>>
- string.gsub(s: string, pattern: string, repl: string | Record<string, string> | ((...matches: string[]) => string), n?: number): LuaMultiReturn<[string, number]>
- string.len(s: string): number
- string.lower(s: string): string
- string.match(s: string, pattern: string, init?: number): LuaMultiReturn<string[]>
- string.rep(s: string, n: number): string
- string.reverse(s: string): string
- string.sub(s: string, i: number, j?: number): string
- string.upper(s: string): string

### table

- table.concat(list: (string | number)[], sep?: string, i?: number, j?: number): string
- table.insert<T>(list: T[], value: T): void
- table.insert<T>(list: T[], pos: number, value: T): void
- table.maxn(table: object): number
- table.remove<T>(list: T[], pos?: number): T | undefined
- table.sort<T>(list: T[], comp?: (a: T, b: T) => boolean): void