Skip to Content
defold-typescript
Get startedGuidesAPILibraries
CLI

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 project

Tip

build regenerates this declaration before it transpiles, and watch refreshes it whenever you save a .go, a .collection, a .collectionproxy or .collectionfactory, or game.project. Reach for the verb itself for a one-off, or for a CI step that runs neither.

The 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 every wave component 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, camera and gui. camera registers from Defold 1.13.0 on, the first version whose API declares camera properties. gui registers wherever the gui namespace 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/player is the bootstrap world: the one collection your game.project names under [bootstrap] main_collection.
  • A socket:/path key like mylevel:/enemy is a proxy world. A collection opened through a collection proxy runs in a world of its own, named by the proxied collection's own name: 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 to game.project does not by itself put its scenes in the universe; run resolve and 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, build and watch — the URL, why it contributed nothing, and the defold-typescript resolve run that repairs it — and --json carries the same strings in warnings. 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. Running resolve clears 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 string

A 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>" }

On this page