typescript-to-gdscript 0.1.0 → 0.1.1

package/README.md

@@ -4,8 +4,6 @@ Write Godot 4 scripts in TypeScript. Get autocomplete and type-checking for the
 
 ![](https://raw.githubusercontent.com/nnn3d/typescript-to-gdscript/HEAD/docs/assets/convert.webp)
 
-> Have an existing GDScript project? Bulk-convert it to TypeScript with [tstogd initial-convert-gd-to-ts](docs/gd-to-ts-migration.md).
-
 ## Why
 
 GDScript is great for getting things on screen, but its type system and tooling are intentionally lightweight. The bigger a project gets, the more that costs you: typos surface at runtime, refactors are risky, and autocomplete only goes so far. TypeScript was built for exactly this problem, and it has had a decade of investment poured into making large codebases safe to change.
@@ -24,13 +22,55 @@ The output is clean, idiomatic `.gd` you can read and ship — TypeScript is the
 
 - **Type-safe Godot API** — all 900+ engine classes generated as `.d.ts` from the official Godot XML docs, with nullable reference types where appropriate
 - **Live IDE diagnostics** — TypeScript language service plugin surfaces converter and Godot CLI errors as squiggles, on unsaved buffers
-- **Watch mode** — auto-convert on save, then run a debounced full-project check (TypeScript + converter + Godot CLI)
+- **Watch mode** — auto-convert on save and keep typings in sync (it watches your `.tscn` scenes and assets too), then run a debounced full-project check (TypeScript + converter + Godot CLI)
 - **Source maps** — Godot script parse errors, runtime errors and stack traces map back to your TypeScript line/column
 - **Scene and path typings** — `get_node()`, `get_parent()`, `get_child()`, `load()`, `preload()` and group queries typed from your project files
 - **`gd` namespace** — strongly-typed helpers for GDScript-only constructs (signals, decorators, match, operator overloading)
 - **Addons supported** — typings for third-party GDScript addons, consumable from TypeScript
 - **GD → TS migration** — one-shot bulk converter for existing projects
 
+### Showcase
+
+<details>
+<summary>Scene and path type hints</summary>
+
+Given this scene structure:
+
+![](https://raw.githubusercontent.com/nnn3d/typescript-to-gdscript/HEAD/docs/assets/showcase_scene.png)
+
+You get type hints for this:
+
+![](https://raw.githubusercontent.com/nnn3d/typescript-to-gdscript/HEAD/docs/assets/showcase_hint_1.png)
+
+…or this:
+
+![](https://raw.githubusercontent.com/nnn3d/typescript-to-gdscript/HEAD/docs/assets/showcase_hint_2.png)
+
+…or even this:
+
+![](https://raw.githubusercontent.com/nnn3d/typescript-to-gdscript/HEAD/docs/assets/showcase_hint_3.png)
+
+`preload()` is typed too:
+
+![](https://raw.githubusercontent.com/nnn3d/typescript-to-gdscript/HEAD/docs/assets/showcase_preload.png)
+
+</details>
+
+<details>
+<summary>GDScript and converter errors in TypeScript code</summary>
+
+GDScript doesn't allow a static and an instance member to share the same name — though TypeScript does. Your IDE surfaces the GDScript error at the exact spot in your `.ts`:
+
+![](https://raw.githubusercontent.com/nnn3d/typescript-to-gdscript/HEAD/docs/assets/showcase_gdscript_error.png)
+
+For edge cases — like using the result of `&&` as a value — you get a converter error instead, because logical operations in GDScript always return a boolean:
+
+![](https://raw.githubusercontent.com/nnn3d/typescript-to-gdscript/HEAD/docs/assets/showcase_converter_error.png)
+
+You also get all of these errors (along with the TypeScript errors themselves) from the `convert` CLI command.
+
+</details>
+
 ## Quick start
 
 ```bash
@@ -41,10 +81,12 @@ tstogd init # interactive: writes tstogd.json + tsconfig.json + installs typescr
 Then:
 
 1. Write a `.ts` class in your TS source dir (default `src/`).
-2. `tstogd convert` — emits `.gd` files into your output dir (default `scripts/`).
+2. `tstogd convert` — emits `.gd` into your output dir (default `scripts/`), regenerates all typings, and runs a full diagnostic check.
 3. Attach the `.gd` file in Godot as you normally would. Configure Godot's external editor to point at your IDE for TS language server and one-click jump-to-source ([guide](docs/ide-integration.md)).
 
-Use `tstogd watch` during development for auto-conversion plus live diagnostics.
+**That's the whole loop — `convert` and `watch` are the only commands you need in normal use.** Each one converts your code _and_ regenerates every typing (scene, script, resource, addon) in the same pass, so `get_node()` paths, `res://` references, and group queries stay in sync without any extra step. Most projects never run another CLI command.
+
+For day-to-day work, run **`tstogd watch`**: it auto-converts on save, watches your `.tscn` scenes and assets so scene typings refresh the instant you change the tree in Godot, and runs a debounced full-project check feeding live IDE diagnostics.
 
 ### Requirements
 
@@ -56,19 +98,30 @@ Use `tstogd watch` during development for auto-conversion plus live diagnostics.
 
 Setup `tstogd.json` and `tsconfig.json` in your project - for full template and field reference see [docs/configuration.md](docs/configuration.md).
 
+### Migration from existing GDScript
+
+Have an existing GDScript project? Bulk-convert it to TypeScript with [tstogd initial-convert-gd-to-ts](docs/gd-to-ts-migration.md).
+
 ## CLI
 
+In everyday use you only need these three:
+
+```bash
+tstogd init                # one-time interactive scaffold (tsconfig + tstogd.json + ts-plugin)
+tstogd convert             # convert TS → GD + regenerate all typings + full diagnostic check
+tstogd watch               # the same, continuously: auto-convert on save, live diagnostics
+```
+
+`convert` and `watch` already regenerate every typing (scene, script, resource, addon) as part of the run — there is no separate "generate typings" step to remember. The commands below cover one-off or advanced situations, and most projects never touch them:
+
 ```bash
-tstogd init                # interactive scaffold (tsconfig + tstogd.json + ts-plugin)
-tstogd convert             # convert TS → GD (cached, with diagnostic check)
-tstogd watch               # auto-convert on change + debounced full check
-tstogd generate-typings    # generate scene + script typings
-tstogd clear-cache         # clear conversion cache
+tstogd generate-typings    # regenerate typings standalone (convert/watch do this for you)
+tstogd clear-cache         # clear the conversion cache (e.g. after upgrading the converter)
 ```
 
 Full reference in [docs/cli.md](docs/cli.md). Specialized commands:
 
-- [`initial-convert-gd-to-ts`](docs/gd-to-ts-migration.md) — bulk migration of an existing GDScript project to TypeScript
+- [`initial-convert-gd-to-ts`](docs/gd-to-ts-migration.md) — one-shot bulk migration of an existing GDScript project to TypeScript
 - [`generate-gdscript-global-typings`](docs/typings.md#tstogd-generate-gdscript-global-typings), [`generate-addon-typings`](docs/typings.md#tstogd-generate-addon-typings) — typings generation
 - [`open-editor`](docs/ide-integration.md#tstogd-open-editor) — Godot external-editor integration
 
@@ -86,123 +139,114 @@ Each `.ts` file must contain exactly one class. Named classes (`class Foo`) are
 - `let` and `const` both convert to GDScript `var`. **Use `let`** — TS `var` is restricted (GDScript `var` ≈ TS `let`, not TS `var`).
 - `undefined` is restricted — use `null`. Optional property access (`obj.foo` where the type includes `undefined`) auto-converts to `obj.get("foo")`. Same for `obj["key"]` with an undefined type. Class-field access stays direct.
 - `TSOnly<T>` — type-level wrapper, stripped at conversion.
+- Only types GDScript actually has get an annotation. Godot classes/value types and your own `class_name` classes (including ones imported from another file) keep their type; plain `interface`s, `object`, `type` aliases, and unknown/unresolved names have the annotation **omitted** (bare untyped `var x` / `func f(x)`) rather than emitting a bogus GD type. See [docs/transform-rules.md#type-annotations--what-gets-emitted](docs/transform-rules.md#type-annotations--what-gets-emitted).
 
 For comments, async, `this` / `self`, logical operators, and constructor mapping, see [docs/transform-rules.md](docs/transform-rules.md).
 
 ## Cheat sheet
 
-Cheat sheet with all basics to write scripts, with comments showing the generated GDScript. For advanced helpers and deep dive, see the [**full cheat sheet** in docs/transform-rules.md](docs/transform-rules.md#full-cheat-sheet).
+Basics for writing scripts For advanced helpers and the deep dive, see the [**full cheat sheet** in docs/transform-rules.md](docs/transform-rules.md#full-cheat-sheet).
 
 ```typescript
-// ── Inner classes, class-level constants & enums (namespace merging) ──
-// A `namespace Player { ... }` block paired with the same-named class
-// lifts each `export`ed member into the class as a nested member.
-// Put constants and enums INSIDE the namespace — that's how GD
-// class-level `const` and `enum` are declared.
+// Use imports instead of global classes for better DX
+// Can be changed by `converterOptions.generateGlobalClassTypes` config option
+import { PlayerSprite, type PlayerSpriteState } from './PlayerSprite';
+
+// Inner classes, class-level constants & enums.
+// A `namespace Player` merged with class `Player`
+// lifts each exported member onto the class.
 export namespace Player {
-  export const MAX_HP = 100; // → const MAX_HP = 100   (on Player)
+  export const MAX_HP = 100;
 
   export enum State {
     IDLE,
     RUNNING,
-  } // → enum State { ... }   (on Player)
+  }
 
   export class Bullet extends Node2D {
-    // → class Bullet extends Node2D:
-    damage: int = 10; //       var damage: int = 10
+    damage: int = 10;
   }
 }
 
 export class Player extends CharacterBody2D {
-  // ── Statics (mutable) — for constants, use the namespace block above ──
-  static MAX_INSTANCES = 8; // → static var MAX_INSTANCES = 8
-  // `readonly` is a TS-only contract — emits a plain `var` on GD.
-
-  // ── Field decorators ─────────────────────────────────────────────
-  // Every Godot annotation works as a decorator.
-  // `@exports` is the only special alias:
-  // `@export` is a TS reserved word, so the plural form emits
-  @exports speed: float = 200.0; // → @export var speed: float = 200.0
-  @export_range(0, 100) health: int = 100; // → @export_range(0, 100) var health: int = 100
-  @onready sprite: Sprite2D; // → @onready var sprite: Sprite2D
-
-  // ── Signals — named tuple labels become GD arg names ─────────────
-  health_changed = gd.signal<[from: int, to: int]>(); // → signal health_changed(from: int, to: int)
-  died = gd.signal(); // → signal died
-
-  // ── Constructor → _init ──────────────────────────────────────────
+  // Statics (mutable); for constants use the namespace
+  static MAX_INSTANCES = 8;
+
+  // Field decorators. `@exports` aliases `@export`
+  // (a TS reserved word); other annotations are 1:1
+  @exports speed: float = 200.0;
+  @export_range(0, 100) health: int = 100;
+  @onready sprite: PlayerSprite = this.get_node('Sprite');
+  @onready sprite_state: PlayerSpriteState = this.sprite.get_state();
+
+  // Signals; tuple labels become GD arg names
+  health_changed = gd.signal<[from: int, to: int]>();
+  died = gd.signal();
+
+  // Constructor replaces _init
   constructor(speed: float = 200.0) {
-    // → func _init(speed: float = 200.0):
-    this.speed = speed; //       self.speed = speed
+    this.speed = speed;
   }
 
-  // ── Getters / setters — native TS accessors ──────────────────────
+  // Getters / setters (native TS accessors)
   get score(): int {
     return this.score;
-  } // → var score: int:
+  }
   set score(v: int) {
     this.score = v;
-  } //       get: return score
-  //       set(value): score = value
+  }
 
-  // ── Async / await — Promise<T> unwraps to T on the GD side ───────
+  // Async / await; Promise<T> unwraps to T
   async long_task(): Promise<int> {
-    // → func long_task() -> int:
     await this.get_tree().create_timer(1).timeout;
     return 42;
   }
 
   _process(delta: float) {
-    // → func _process(delta: float):
-    // ── Operators ──────────────────────────────────────────────────
-    let eq = this.health === 0; // → var eq      = self.health == 0
-    let ternary = eq ? 1 : 2; // → var ternary = 1 if eq else 2
+    // Operators
+    let eq = this.health === 0;
+    let ternary = eq ? 1 : 2;
 
-    // ── Math on value types (Vector2, Color, …) needs gd.ops ───────
-    let pos = gd.ops.add(this.position, Vector2(1, 0)); // → var pos = (self.position + Vector2(1, 0))
-    // Available: add, sub, mul, div, rem, eq, ne, gt, gte, lt, lte, plus (unary), minus (unary)
+    // Math on value types (Vector2, Color, …) needs gd.ops
+    let pos = gd.ops.add(this.position, Vector2(1, 0));
+    // Also available: add, sub, mul, div, rem, eq, ne, gt, gte, lt, lte, plus (unary), minus (unary)
 
-    // ── Type casting / checking ────────────────────────────────────
-    let body = gd.as(this.get_node('Body'), CharacterBody2D); // → var body = self.get_node("Body") as CharacterBody2D
+    // Type casting / checking
+    // self.get_node("Body") as CharacterBody2D
+    let body = gd.as(this.get_node('Body'), CharacterBody2D);
     if (body instanceof CharacterBody2D) {
-      /* class check */
-    } // → if body is CharacterBody2D:
+      /* body is CharacterBody2D */
+    }
     if (gd.is(this.health, int)) {
-      /* primitive   */
-    } // → if self.health is int:
+      /* health is int */
+    }
 
-    // ── Object construction ────────────────────────────────────────
-    let bullet = new Player.Bullet(); // → var bullet = Bullet.new()
+    // Object construction instead of Player.Bullet.new()
+    let bullet = new Player.Bullet();
 
-    // ── Dictionaries (string keys — for non-string keys use gd.dict) ──
-    let stats = { name: 'Hero', hp: 100 }; // → var stats = { "name": "Hero", "hp": 100 }
+    // Dictionaries (other keys: gd.dict)
+    let stats = { name: 'Hero', hp: 100 };
 
-    // ── Strings, StringName, NodePath ──────────────────────────────
-    let greet = `Hi ${this.name}!`; // → var greet = "Hi " + str(self.name) + "!"
-    let path = NodePath('Body/Sprite'); // → var path  = ^"Body/Sprite"
-    let sig = StringName('died'); // → var sig   = &"died"
+    // Strings, StringName, NodePath
+    let greet = `Hi ${this.name}!`;
+    let path = NodePath('Body/Sprite');
+    let sig = StringName('died');
 
-    // ── Control flow ───────────────────────────────────────────────
-    for (let s of range(3)) print(s); // → for s in range(3): print(s)
+    // Control flow
+    for (let s of range(3)) print(s);
 
-    // ── Match — native TS switch round-trips with GD `match` ───────
-    switch (
-      this.health // → match self.health:
-    ) {
+    // Match (TS switch round-trips with GD match)
+    switch (this.health) {
       case 0:
         this.died.emit();
-        break; //       0: self.died.emit()
       default:
         print('alive');
-        break; //       _: print("alive")
     }
   }
 
   _ready() {
-    // → func _ready():
-    // Signals — emit and connect
-    this.health_changed.emit(0, 100); // → self.health_changed.emit(0, 100)
     this.health_changed.connect(this._on_health_changed);
+    this.health_changed.emit(0, 100);
   }
 
   _on_health_changed(from: int, to: int) {
@@ -214,35 +258,117 @@ export class Player extends CharacterBody2D {
 }
 ```
 
-#### Useful global types
-
-Each interface is a map from a string literal (a `res://` path or a group name) to the typed entity that path resolves to. You index them directly to get the typed value:
+<details>
+<summary>Result gdscript:</summary>
+
+```gdscript
+extends CharacterBody2D
+class_name Player
+
+const MAX_HP = 100
+
+enum State { IDLE, RUNNING }
+
+class Bullet extends Node2D:
+	var damage: int = 10
+
+# Statics (mutable); for constants use the namespace
+static var MAX_INSTANCES = 8
+# Field decorators. `@exports` aliases `@export`
+# (a TS reserved word); other annotations are 1:1
+@export
+var speed: float = 200.0
+@export_range(0, 100)
+var health: int = 100
+@onready
+var sprite: PlayerSprite = self.get_node("Sprite")
+@onready
+var spriteState = self.sprite.get_state()
+# Signals; tuple labels become GD arg names
+signal health_changed(from: int, to: int)
+signal died
+
+# Constructor replaces _init
+func _init(speed: float = 200.0):
+	self.speed = speed
+
+var score: int:
+	get:
+		return score
+	set(v):
+		score = v
+
+# Async / await; Promise<T> unwraps to T
+func long_task() -> int:
+	await self.get_tree().create_timer(1).timeout
+	return 42
+
+func _process(delta: float):
+	# Operators
+	var eq = self.health == 0
+	var ternary = 1 if eq else 2
+	# Math on value types (Vector2, Color, …) needs gd.ops
+	var pos = (self.position + Vector2(1, 0))
+	# Also available: add, sub, mul, div, rem, eq, ne, gt, gte, lt, lte, plus (unary), minus (unary)
+	# Type casting / checking
+	# self.get_node("Body") as CharacterBody2D
+	var body = self.get_node("Body") as CharacterBody2D
+	if body is CharacterBody2D:
+		pass
+	if self.health is int:
+		pass
+	# Object construction instead of Player.Bullet.new()
+	var bullet = self.Bullet.new()
+	# Dictionaries (other keys: gd.dict)
+	var stats = {
+		"name": "Hero",
+		"hp": 100,
+	}
+	# Strings, StringName, NodePath
+	var greet = "Hi " + str(self.name) + "!"
+	var path = NodePath("Body/Sprite")
+	var sig = StringName("died")
+	# Control flow
+	for s in range(3):
+		print(s)
+	# Match (TS switch round-trips with GD match)
+	match self.health:
+		0:
+			self.died.emit()
+		_:
+			print("alive")
+
+func _ready():
+	self.health_changed.connect(self._on_health_changed)
+	self.health_changed.emit(0, 100)
+
+func _on_health_changed(from: int, to: int):
+	pass
+
+func die():
+	pass
+```
 
-| Interface          | Keys                                                         | Values                                                                                                                                            | Example                                                          |
-| ------------------ | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
-| `GodotResources`   | every asset path (`.tscn`, `.gd`, `.tres`, images, audio, …) | The resource type the path resolves to — `PackedScene<Root>` for scenes, `typeof Class` for scripts, the concrete `Resource` subclass for `.tres` | `let mat: GodotResources["res://player_material.tres"]`          |
-| `GodotScripts`     | `.gd` script paths                                           | `typeof <Class>` — the class constructor for the script                                                                                           | `const GameManager: GodotScripts["res://GameManager.gd"]`        |
-| `GodotScenes`      | `.tscn` paths                                                | The **root node** type of the scene (with full tree attached)                                                                                     | `let root: GodotScenes["res://Level.tscn"]`                      |
-| `GodotSceneTrees`  | `.tscn` paths                                                | The **tree** type — used when you need to index descendants directly                                                                              | `type Tree = GodotSceneTrees["res://Player.tscn"]`               |
-| `GodotGroups`      | group names declared in `.tscn` files                        | `{ [scenePath]: union of node types in that group }`                                                                                              | `GodotGroups["enemies"]["res://Level.tscn"]` → `Goblin \| Slime` |
-| `GodotConnections` | scene paths that have `[connection]` entries                 | `{ "Node.signal": _GDSignalConnection<…> }` — connection metadata                                                                                 | `GodotConnections["res://UI.tscn"]["Button.pressed"]`            |
+</details>
 
-The Godot-typed `load()`, `preload()`, `get_node()`, and autoload singletons all index these interfaces under the hood.
+#### Useful global types
 
-#### The `*Name` key-union aliases
+Each interface maps a string literal (a `res://` path or group name) to the type it resolves to — index it directly, e.g. `GodotResources["res://player.tres"]` or `GodotScripts["res://player.gd"]`:
 
-Each base interface has a parallel alias defined as `keyof <Interface>`, so you can constrain a function argument to **only paths/names that exist in the project**:
+- **`GodotResources`** — any asset path → its resource type (`PackedScene<Root>`, `typeof Class`, or the concrete `Resource` subclass)
+  - **`GodotResourceName`** (= `keyof GodotResources`) — any `res://…` asset
+- **`GodotScripts`** — `.gd` path → `typeof <Class>` (the script constructor)
+  - **`GodotScriptName`** (= `keyof GodotScripts`) — a `.gd` path
+- **`GodotScenes`** — `.tscn` path → the scene's **root node** type
+  - **`GodotSceneName`** (= `keyof GodotScenes`) — a `.tscn` path
+- **`GodotSceneTrees`** — `.tscn` path → the **tree** type, for indexing descendants directly
+  - **`GodotSceneTreeName`** (= `keyof GodotSceneTrees`) — same set as `GodotSceneName`, for the tree rather than the root
+- **`GodotGroups`** — group name → union of the node types in that group
+  - **`GodotGroupName`** (= `keyof GodotGroups`) — a group identifier (`"enemies"`, …)
 
-| Alias                      | Equivalent to            | Typical use                                                             |
-| -------------------------- | ------------------------ | ----------------------------------------------------------------------- |
-| `GodotResourceName`        | `keyof GodotResources`   | `res://…` to any asset                                                  |
-| `GodotSceneName`           | `keyof GodotScenes`      | `res://…` to a `.tscn`                                                  |
-| `GodotSceneTreeName`       | `keyof GodotSceneTrees`  | Same set as `GodotSceneName`; pick when you want the tree, not the root |
-| `GodotScriptName`          | `keyof GodotScripts`     | `res://…` to a `.gd`                                                    |
-| `GodotGroupName`           | `keyof GodotGroups`      | Group identifier (`"enemies"`, `"entities"`, …)                         |
-| `GodotConnectionSceneName` | `keyof GodotConnections` | Scene paths that have `[connection]` entries                            |
+The Godot-typed `load()`, `preload()`, `get_node()`, and autoload singletons all index these under the hood.
 
-`keyof` is resolved lazily, so each alias automatically picks up new entries as more files are converted. Typos in resource paths or group names become compile-time errors instead of silent runtime failures:
+That types are resolved lazily, so each alias automatically picks up new entries as more files are converted. Typos in resource paths or group names become compile-time errors instead of silent runtime failures:
 
 ```typescript
 class AssetLoader extends Node {
@@ -256,9 +382,9 @@ class AssetLoader extends Node {
 
   _ready() {
     this.preload_asset('res://Player.tscn'); // ✅ typed
-    this.preload_asset('res://does_not_exist.png'); // ❌ TS2345
+    this.preload_asset('res://does_not_exist.png'); // ❌ error
     this.count_in_group('enemies'); // ✅ typed
-    this.count_in_group('typo'); // ❌ TS2345
+    this.count_in_group('typo'); // ❌ error
   }
 }
 ```

package/dist/converter/common/index.d.ts

@@ -40,6 +40,15 @@ export interface TransformContext {
      * `extends "res://..."` are taken relative to this directory.
      */
     projectRoot: string;
+    /**
+     * Godot class registry. Used to recognise Godot built-in types (classes,
+     * value-type constructors, global enums) by name when classifying TS type
+     * annotations — see {@link tsTypeNodeToGdType}. May be `undefined` when the
+     * registry could not be resolved, in which case classification can only
+     * emit types it proves are classes/enums via the checker and drops every
+     * other name (Godot built-ins can no longer be recognised by name).
+     */
+    registry?: GodotClassRegistry;
 }
 /**
  * Sentinel TS class name used for anonymous addon scripts (a `.gd`
@@ -147,12 +156,19 @@ export declare function isFloatType(type: ts.Type, checker: ts.TypeChecker): boo
 /**
  * Converts a TypeScript type to its GDScript type annotation string.
  * Returns null if the type should be omitted.
+ *
+ * NOTE: unlike {@link tsTypeNodeToGdType}, this `ts.Type`-based variant does
+ * NOT classify reference types — it returns the symbol name verbatim for any
+ * class-like type, so an `object`/`interface`/unknown type would leak a bogus
+ * annotation. It is currently unused for emission (kept only for its own
+ * recursion). Do not wire it into an emit path without adding the same
+ * class/enum/registry classification `classifyTypeReferenceName` applies.
  */
 export declare function tsTypeToGdType(type: ts.Type, checker: ts.TypeChecker): string | null;
 /**
  * Converts a TypeScript type annotation node to GDScript type string.
  */
-export declare function tsTypeNodeToGdType(typeNode: ts.TypeNode | undefined, checker: ts.TypeChecker, sourceFile: ts.SourceFile, className?: string): string | null;
+export declare function tsTypeNodeToGdType(typeNode: ts.TypeNode | undefined, checker: ts.TypeChecker, sourceFile: ts.SourceFile, className?: string, registry?: GodotClassRegistry): string | null;
 /**
  * True when `gdType` refers to a Godot class (Node, Resource, Material, user
  * class, ...) — a type that can legitimately hold `null` in GDScript. False

package/dist/converter/common/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/converter/common/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/converter/common/index.ts"],"names":[],"mappings":"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"}

package/dist/converter/common/index.js

@@ -107,6 +107,13 @@ export function isFloatType(type, checker) {
 /**
  * Converts a TypeScript type to its GDScript type annotation string.
  * Returns null if the type should be omitted.
+ *
+ * NOTE: unlike {@link tsTypeNodeToGdType}, this `ts.Type`-based variant does
+ * NOT classify reference types — it returns the symbol name verbatim for any
+ * class-like type, so an `object`/`interface`/unknown type would leak a bogus
+ * annotation. It is currently unused for emission (kept only for its own
+ * recursion). Do not wire it into an emit path without adding the same
+ * class/enum/registry classification `classifyTypeReferenceName` applies.
  */
 export function tsTypeToGdType(type, checker) {
     // Check for int/float aliases
@@ -165,7 +172,7 @@ export function tsTypeToGdType(type, checker) {
 /**
  * Converts a TypeScript type annotation node to GDScript type string.
  */
-export function tsTypeNodeToGdType(typeNode, checker, sourceFile, className) {
+export function tsTypeNodeToGdType(typeNode, checker, sourceFile, className, registry) {
     if (!typeNode)
         return null;
     // Check for literal type names like `int` and `float`
@@ -191,23 +198,9 @@ export function tsTypeNodeToGdType(typeNode, checker, sourceFile, className) {
                 return null;
             if (arg.kind === ts.SyntaxKind.VoidKeyword)
                 return null;
-            return tsTypeNodeToGdType(arg, checker, sourceFile, className);
-        }
-        // Type aliases (non-class) → omit annotation. GDScript has no equivalent
-        // and `Variant` conveys nothing beyond "untyped", which the bare `var x`
-        // / `func f(x)` forms already express.
-        const symbol = checker.getSymbolAtLocation(typeNode.typeName);
-        if (symbol) {
-            const declarations = symbol.getDeclarations();
-            if (declarations && declarations.length > 0) {
-                const decl = declarations[0];
-                if (ts.isTypeAliasDeclaration(decl)) {
-                    return null;
-                }
-            }
+            return tsTypeNodeToGdType(arg, checker, sourceFile, className, registry);
         }
-        // Strip generic args for class types
-        return name;
+        return classifyTypeReferenceName(typeNode, name, checker, registry);
     }
     // Keyword types
     if (typeNode.kind === ts.SyntaxKind.NumberKeyword)
@@ -228,7 +221,7 @@ export function tsTypeNodeToGdType(typeNode, checker, sourceFile, className) {
         return null;
     // Array type: T[] -> Array[T]
     if (ts.isArrayTypeNode(typeNode)) {
-        const elementType = tsTypeNodeToGdType(typeNode.elementType, checker, sourceFile, className);
+        const elementType = tsTypeNodeToGdType(typeNode.elementType, checker, sourceFile, className, registry);
         return elementType ? `Array[${elementType}]` : 'Array';
     }
     // Function type: () => void -> Callable
@@ -243,7 +236,7 @@ export function tsTypeNodeToGdType(typeNode, checker, sourceFile, className) {
     if (ts.isUnionTypeNode(typeNode)) {
         const nonNull = typeNode.types.filter((t) => !isNullLiteralTypeNode(t));
         if (nonNull.length === 1 && nonNull.length !== typeNode.types.length) {
-            return tsTypeNodeToGdType(nonNull[0], checker, sourceFile, className);
+            return tsTypeNodeToGdType(nonNull[0], checker, sourceFile, className, registry);
         }
         return null;
     }
@@ -252,6 +245,63 @@ export function tsTypeNodeToGdType(typeNode, checker, sourceFile, className) {
     }
     return null;
 }
+/**
+ * Classify a TS type-reference name and decide whether it should be emitted
+ * as a GDScript type annotation.
+ *
+ * Only types that GDScript actually has are emitted:
+ *   - User / Godot `class` declarations and `enum` declarations (resolved via
+ *     the TS checker — user classes resolve locally even without the Godot
+ *     typings loaded).
+ *   - Godot built-in types recognised *by name* from the registry: classes
+ *     (`Node`, `Node2D`, …), value-type constructors (`Vector2`, `Color`,
+ *     `Dictionary`, …) and global enums (`Key`, `MouseButton`, …). The
+ *     name-based check is what keeps Godot types working in test/program
+ *     setups that don't load the Godot `.d.ts` typings.
+ *
+ * Everything else — type aliases, plain interfaces, `object`-like types,
+ * dotted refs that don't resolve to a class/enum (`Node.ProcessMode`,
+ * `Outer.SomeIface`) and unknown / unresolved names — is omitted (the bare
+ * `var x` / `func f(x)` form is the idiomatic "untyped" GD). GD type hints are
+ * optional, so dropping an unverifiable type is always safe; emitting a bogus
+ * one would break the `.gd`.
+ *
+ * Omitting is always safe; emitting an annotation GDScript doesn't recognise
+ * breaks the generated `.gd`. So when no registry is available the converter
+ * can't recognise Godot built-ins by name — it only emits types it can prove
+ * are classes/enums (via the checker) and drops the rest, rather than risk
+ * leaking an invalid type.
+ */
+function classifyTypeReferenceName(typeNode, name, checker, registry) {
+    // Resolve the symbol, following import aliases to the real declaration so
+    // that types imported from another file are classified by what they are,
+    // not by the `ImportSpecifier` binding.
+    let symbol = checker.getSymbolAtLocation(typeNode.typeName);
+    if (symbol && symbol.flags & ts.SymbolFlags.Alias) {
+        symbol = checker.getAliasedSymbol(symbol);
+    }
+    const declarations = symbol?.getDeclarations() ?? [];
+    // Type aliases have no GDScript equivalent → omit.
+    if (declarations.some(ts.isTypeAliasDeclaration))
+        return null;
+    // User / Godot `class` and `enum` declarations are valid GD types.
+    if (declarations.some((d) => ts.isClassDeclaration(d) || ts.isEnumDeclaration(d))) {
+        return name;
+    }
+    // Godot built-in types are recognised by name (works without typings).
+    if (registry &&
+        (registry.hasClass(name) ||
+            registry.isConstructor(name) ||
+            registry.isGlobalEnum(name))) {
+        return name;
+    }
+    // Whatever is left is a non-class type (interface, `object`-like, namespace),
+    // a dotted ref we can't verify (`Node.ProcessMode`, `Outer.SomeIface`), or an
+    // unknown / unresolved name — none provably a GD type. Omit the annotation:
+    // GD type hints are optional, so dropping a type is always safe, whereas
+    // emitting a bogus one breaks the generated GDScript.
+    return null;
+}
 /** True for the `null` keyword wrapped in a `LiteralTypeNode`. */
 function isNullLiteralTypeNode(node) {
     return (ts.isLiteralTypeNode(node) &&