Skip to Content
defold-typescript
Get startedGuidesAPILibraries
CLI

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.

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 (msg, vmath, sys, go, …) is available in every kind, except that a render script has no game object, so it cannot call a function that needs one: all of sprite, factory, physics and their kin, and most of go. See API availability by script kind for the full list.

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 standalone tsconfig.json written into a single-kind source directory. It extends the root config and narrows compilerOptions.types to that kind's subpath:

Script kindtypes entrypointNamespaces
.script@defold-typescript/types/scriptuniversal only
.gui_script@defold-typescript/types/gui-scriptuniversal + gui
.render_script@defold-typescript/types/render-scriptuniversal + render, without the functions that need a game object
.editor_script@defold-typescript/types/editor-scripteditor only

.editor_script is the odd one out: it runs in the editor's own Lua VM, so its surface is disjoint from the runtime kinds rather than a narrowing of them — no go, msg or vmath. It is offered like any other kind, so a directory holding only editor scripts is eligible and walls to that subpath; see editor scripts.

Under a pinned Defold surface a wall narrows to <surface>/<kind> only for the kinds that surface actually wrote; for every other kind it keeps naming the installed @defold-typescript/types/<kind> entrypoint. Which kinds a surface writes depends on how it was produced — see Pinning a Defold target. A surface generated on the fly from Defold's reference docs carries the runtime trio, so its runtime walls narrow; a surface copied from a committed snapshot carries only editor-script, so its runtime walls keep the installed subpath. Either surface carries editor-script only when the Defold target it was built from ships an editor-scripting document of its own, which today only the current default target does.

Narrowing covers the import as well as the ambient namespaces. A wall that narrows to a pinned kind also redirects the @defold-typescript/types/<kind> factory import into the same pinned file, so the factory and the namespaces come from one surface rather than from the pinned one and the installed release. That is why a member the pinned release does not declare is now a compile error inside a walled directory, even though the installed package still declares it. Walls that are not pinned, and pinned walls for a kind the surface did not write, keep the installed entrypoint and are unaffected. That redirect is the only module mapping a wall manages: mappings you declare in the wall's own tsconfig.json and in the root config keep resolving inside the walled directory, and dropping the pin removes only what walling added.

The root tsconfig.json excludes each walled directory from its own program, and wall --check type-checks every wall 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. Your editor reads the same configs: a file inside a wall uses that wall's surface, and every other file uses the root's.

A wall also sets compilerOptions.outDir to null. build reads outDir from the root config alone, so this changes no output; inherited into a wall, the root's outDir would make TypeScript treat the walled directory as the root of every source, and a wall file importing a module outside it would fail with TS6059. Running wall <dir> for any walled directory rewrites every existing wall into this shape.

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

Inheritance. A wall narrows every directory beneath it, so declare it at the boundary — src/gui1, not src/gui/hud and src/gui/menu separately. A directory whose sources all live in subdirectories is eligible on their behalf, and a src/gui/settings/ added later is narrowed with no second wall run.

Override. A descendant that declares its own wall replaces the inherited one: the ancestor excludes that descendant from its program, so the descendant's kind subpath cannot widen the ancestor. Without the exclusion the two would intersect — the descendant's files would stay in the ancestor's program and inject their namespaces there, letting gui.* type-check inside a script wall.

The test folder. A wall at src also excludes test/**, so the Bun tests and declarations under src/test/ never join its program. Running wall src rewrites an existing wall there into this shape.

Kind-neutral helpers. A .ts with no lifecycle factory declares no kind, so it never makes a directory eligible and never blocks an ancestor from rolling up to a single kind. A helper runs in the script that calls it, so wall --check checks it against each kind that imports it:

  • Put a helper shared across kinds outside every wall, for example in src/shared/. A helper inside a wall belongs to that wall's kind alone.
  • Each wall that imports the helper checks it against that wall's kind. A render wall importing a helper that calls go.get_position fails, with the error reported in the helper under the render wall; a gui wall importing a helper that calls gui.set_text passes.
  • A helper that no wall imports keeps the root's full surface.
  • Your editor checks the helper only against the root's full surface, so a helper's wall errors show up only in wall --check.
  • A file in a wall's program that imports the main @defold-typescript/types entry or another kind's subpath, or names one in a /// <reference types> directive, a helper included, is reported: that import or directive loads more namespaces into the whole wall.

Interactive

Run wall with no arguments in a terminal:

bunx @defold-typescript/cli wall

You get a checkbox of every eligible source directory — including the ancestors that hold no sources of their own — pre-checked to the directories already walled. Checking an unwalled directory walls it; unchecking a walled directory removes its wall. A directory already governed by an ancestor's wall is labelled [inherited from <dir>] rather than pre-checked, since checking it would declare a redundant second 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):

# 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

# Type-check every wall and the root program (writes nothing)
bunx @defold-typescript/cli wall --check
bunx @defold-typescript/cli wall --check --json

wall --check builds one program per wall, plus the root program when any source lies outside the walls, and prints each error as <program>: <file>:<line>:<column>: <message>, where <program> is the wall directory, or . for the root. It exits 1 on any error. --json carries the same errors in wallCheck.programs, one entry per program with its dir, its kind (full for the root) and its diagnostics (file, line, column, code and message; code is 0 for a widening import or /// <reference types> directive). Walls written by an earlier release are composite projects the root references; wall --check reports them without checking anything, and re-running wall <dirs> on the same directories rewrites them.

--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.

wall --list --json also carries resolved: one entry per source directory a wall actually narrows, so an inherited narrowing is traceable to the declaration that caused it. Each entry adds declaredIn (the directory the governing wall is declared on) and origin — "declared" when the directory carries the wall itself, "inherited" when an ancestor's wall governs it. The human --list line names the inherited directories the same way (src/gui/hud <- src/gui).

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:

// 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:

// 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.)

Footnotes

  1. src/ is this guide's shorthand and the scaffold's default, not a fixed location. Your source roots are the include globs in tsconfig.json — ["src/**/*.ts"] out of the box, and any list of folders you set; build and watch compile exactly what those globs match, and ignore exclude. ↩

On this page