Scene types
scene-types reads the .collection and .go files in your project and writes
one declaration file naming every game-object path and component id they
declare. Editors then offer those addresses as completions on the slots typed
for them — msg.post's receiver, go.get's url, and every other address
parameter.
bunx @defold-typescript/cli scene-types . # current folder
bunx @defold-typescript/cli scene-types path/to/project # a specific projectThe declaration lands at .defold-types/scene-addresses.d.ts, beside the
materialized API surface. Like everything else
under .defold-types/, it is generated — never edit it, and never commit it.
What it writes
Two open interfaces, augmented with one key per address the project declares:
declare global {
interface SceneGameObjectAddresses {
"/player/player": true;
}
interface SceneComponentAddresses {
"#controller": "script";
"#sprite": "sprite";
"/player/player#controller": "script";
"/player/player#sprite": "sprite";
}
}Game-object paths are composed the way Defold composes them at runtime: a
collection instanced under the id player contributes /player/<id> for every
object it holds, nested as deeply as your collections nest. A children: edge is
a transform relation, not a path segment, so a child object keeps its own
one-segment address.
Component ids are written in both forms. The same-object #id is offered for
every id the project declares. The object-qualified /path#id is offered wherever
the generator can name the object that owns the component: it reads each composed
path's own prototype — the .go its instances block names, or the payload its
embedded_instances block embeds — so /player/player#sprite is offered while
/level#sprite is not. A qualified key carries the same world axis a path key
does, so a component in a proxy world is offered as mylevel:/enemy#sprite and
never bare.
An object whose prototype the walk could not read is offered no qualified key at all, and the reason is recorded alongside the other gaps the path walk found — withheld rather than guessed, because an empty component set would be indistinguishable from an object that genuinely owns none. Nothing here is a rejection: an address composed at runtime still type-checks, it is simply not offered as a completion.
Component addresses carry their messages and properties
Each component address is written as what the component is. When a component
names a script that your program compiles, its address is that script's module.
Every other component address is its kind: the extension of the resource it
names, or the type of an embedded component.
interface SceneComponentAddresses {
"#wave": typeof import("../src/wave").default;
"/logic#wave": typeof import("../src/wave").default;
"/logic#sprite": "sprite";
"/logic#legacy": "script";
}msg.post("/logic#wave", ...) then completes and checks the ids that script's
onMessage handlers declare. The
source is found by mapping each program file forward to the resource it builds,
so an outDir works. The source must be a defineScript (or defineGuiScript)
file. A script outside your program is written as "script", and a component
whose kind cannot be read is written as true.
Two address forms are linked automatically:
- an absolute, literal component address your scenes declare, such as
"/logic#wave"; - a bare
"#wave", when everywavecomponent in the project is written the same way: the same script, or the same kind.
When two proxied collections declare the same name:, an address under that
socket such as "mylevel:/hero#body" follows the same rule: it is linked only
when every one of those collections writes that component the same way, and is
true otherwise.
An object-relative address such as "buddy#controller", a bare game-object
address and a URL built at runtime are not linked; use msg.url<M>(...) or
CustomMessages for those.
Property keys follow the address
go.get, go.set and go.animate read the property catalog of a literal
address:
- A linked script takes the properties its
defineScript({ properties })declares, plus each element of a vector or quaternion property, such as"target.x". Any other key is a compile error, because the engine raises for it. - A registered kind takes the keys its catalog names at their types. The
registered kinds are
sprite,label,model,mesh,collisionobject(physics.Properties),factory,collectionfactory,particlefx,sound,tilemap,cameraandgui.cameraregisters from Defold 1.13.0 on, the first version whose API declares camera properties.guiregisters wherever theguinamespace loads, so in a directory walled to the script surface a gui address takes the wide value. Any other key, such as a material constant, takes the wide value. - A literal with no
#, such as"."or"/player", is a game object. Its only properties are its transform,go.Properties, so any other key is a compile error.
// src/wave.ts declares defineScript({ properties: { delay: 2 }, ... })
go.get("/logic#wave", "delay"); // number
go.get("/logic#wave", "dleay"); // error: wave declares no dleay
go.set("/logic#sprite", "playback_rate", "fast"); // error: playback_rate is a number
go.set("/logic#sprite", "tint", vmath.vector4()); // a material constant: wide value
go.get(".", "delay"); // error: a game object has no script property"" and "#" resolve to the calling script, so they stay untyped. So do an
address whose kind has no catalog, such as a script outside your program
("script") or a native extension's component, a string variable, a Url and
a Hash. A key passed as hash("delay") is accepted on every address and reads
the wide value. An extension registers its own kind by augmenting the global
SceneComponentCatalogs interface.
Which world an address resolves in
An address has two axes: which world, then which path inside it. Defold
runs more than one game world at a time, and the same /enemy in two of them is
two different objects — so the generator says which one each key means.
- A bare key like
/player/playeris the bootstrap world: the one collection yourgame.projectnames under[bootstrap] main_collection. - A
socket:/pathkey likemylevel:/enemyis a proxy world. A collection opened through a collection proxy runs in a world of its own, named by the proxied collection's ownname:field — not the proxy component's id, and not the file name. From outside that world its objects are only reachable through that socket, so they are never offered bare. - A collection factory prototype has no static address at all. Its
objects only exist under a runtime-generated
/collection[N]/prefix, so the generator offers nothing for them rather than an address that could never resolve.
A world-qualified address only works where the engine crosses worlds for you.
msg.post and msg.url go through the message bus and accept
mylevel:/enemy; every go.* call that resolves an instance or component
handle — go.get_position, go.set_parent, go.animate, go.get/go.set —
resolves inside the world its own script runs in, so a socket-qualified literal
there names an object it can never reach. build and
watch report exactly that case: an address naming a foreign
socket at a slot that stays in the caller's world, with the socket it named and
the world the script actually runs in.
An address is socket-qualified by its :, not by the path after it: the
grammar is [socket:][path][#fragment] with both halves optional, so
mylevel:enemy, mylevel: and mylevel:#body are checked exactly like
mylevel:/enemy. A : inside a path segment is not a socket — /level:1/enemy
is a bare path, because the leading / closes the address's head first.
The boundary is drawn on the side of silence. Nothing is reported for a
msg.post/msg.url slot, for an address that names no socket at all — a bare
/path, a relative id or sub/id, a lone #fragment, each of which
continues the caller's world by construction — for a socket that matches a world
the script runs in, or for a script whose world could not be resolved at all — a
.ts no scene hosts, or one whose scenes the walk could not read. A script a scene
instances in two worlds is reported only when the address disagrees with every
one of them.
If your game.project cannot be read, or declares no [bootstrap] main_collection, no key is offered bare and the reason is named on the warning
channel — the generator says what it could not settle instead of guessing that
every collection is a root. A collection nothing reaches — no bootstrap, proxy,
instance or factory reference — is reported the same way, and contributes no
address.
Your library dependencies count too
The universe is your project's own scenes plus whatever
resolve last unpacked from your library dependencies. A
library shares the collections, game objects and gui scenes under the
[library] include_dirs its own game.project declares — along with the
.collectionproxy and .collectionfactory components that classify them — and
Defold merges those into your project's namespace, so a collection a library
holds at druid/druid.collection is /druid/druid.collection to you, and
instancing it in one of your own collections contributes its objects' addresses
exactly as a local collection would. A library collection its own proxy opens is
addressed under that collection's socket, the same as one of your own.
Two consequences worth knowing:
- It is only as current as your last
resolve. Adding a dependency togame.projectdoes not by itself put its scenes in the universe; runresolveand they appear. - An unresolved dependency is reported, never skipped. A dependency you
declared but have not resolved is named on the warning channel of
scene-types,buildandwatch— the URL, why it contributed nothing, and thedefold-typescript resolverun that repairs it — and--jsoncarries the same strings inwarnings. The exit code is unchanged and the declaration is still written from whatever did resolve: completions come from the partial universe, because a suggestion claims nothing about what is absent. Runningresolveclears it.
Your own file always wins if a project scene and a library scene land on the same path, and the shadowing is reported the same way.
The same universe is what build checks address literals against:
a #fragment naming a component no scene declares becomes a build warning, and a
hole here — an unresolved dependency included — suppresses that check rather than
reporting the fragment.
An address is never rejected
SceneGameObjectAddress and SceneComponentAddress stay widened with
(string & {}). The keys only add suggestions:
const spawned = `/enemy${index}`;
msg.post(spawned, "hello"); // fine — a runtime-composed address is still a stringA property key is checked instead: a key that a linked script does not declare is a compile error, and so is a key outside the transform on a game-object literal, with or without this verb (see Property keys follow the address).
In a project that has never run this verb both interfaces are empty, so no component address is linked. Running it against a project with no scene files at all succeeds and writes an empty-but-valid declaration.
Putting it in your program
The generator writes the file; your tsconfig.json decides whether the compiler
reads it. init and upgrade wire that up for you — both write an include
that already names the declaration:
{
"include": ["src/**/*.ts", ".defold-types/scene-addresses.d.ts"]
}Your own include patterns are preserved and the entry is appended only when
it is absent, so re-running either verb never duplicates it. On a project
scaffolded before this was automatic, one defold-typescript upgrade adds the
entry; adding the line by hand works just as well. Without it the file is
written and ignored, and the addresses stay un-suggested — the same behavior as
not running the verb.
The entry names the file exactly rather than globbing .defold-types/, which
is the project's typeRoots: a pattern there would pull every other
materialized surface into the build's transpile source set. An include entry
that matches nothing is ignored, so the entry is harmless before the verb has
ever run.
Re-runs cost nothing
The keys are sorted, so a project whose scenes did not change re-emits the same bytes, and the verb skips the write entirely rather than touching a file whose content is identical. The write itself goes through a temporary file and a rename, so the editor never reads a half-written declaration.
Build output is skipped: bob writes _generated_*.go copies of your scenes
under build/, and reading those would report every id twice. So are the paths
the scaffolded .defignore names — node_modules/, .defold-types/,
.vscode/. The one exception is .defold-types/dependencies/, which is not
your project's own source at all: it is the library surface resolve writes,
read under the merged paths described above.
Machine-readable output
--json writes exactly one JSON object to stdout:
{
"command": "scene-types",
"ok": true,
"written": [".defold-types/scene-addresses.d.ts"],
"declaration": ".defold-types/scene-addresses.d.ts"
}declaration names the file on every run; written lists it only when this run
actually rewrote it, so a re-run over unchanged scenes reports []. On failure
the envelope carries the reason and no written field:
{ "command": "scene-types", "ok": false, "error": "<message>" }