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 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, without the functions that need a game object |
.editor_script | @defold-typescript/types/editor-script | editor 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_positionfails, with the error reported in the helper under the render wall; a gui wall importing a helper that callsgui.set_textpasses. - 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/typesentry 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 wallYou 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 --jsonwall --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"; // correctImporting 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
-
src/is this guide's shorthand and the scaffold's default, not a fixed location. Your source roots are theincludeglobs intsconfig.json—["src/**/*.ts"]out of the box, and any list of folders you set;buildandwatchcompile exactly what those globs match, and ignoreexclude. ↩