ts2gd

library0.0.36jsnpmunverified

ts2gd is a TypeScript-to-GDScript transpiler for Godot 3.x projects, currently at version 0.0.36. It compiles TypeScript source files directly to GDScript with near-zero runtime overhead and fast incremental compilation (<0.1 seconds after startup). Unlike embedded JavaScript runtimes (e.g., GodotJS), ts2gd outputs native GDScript, ensuring no performance penalty. It enhances developer experience with full TypeScript type safety, autocomplete, and refactoring support. The project is in early beta with occasional breaking changes due to its pre-1.0 status. Development appears active, with updates every few months.

devops

npm install ts2gd

package ↗

INSTALL

IMPORT

SIG · TS2GD

ts2gd

devopsjavascriptv0.0.36

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

init project

✓ ts2gd --init

✗ npm init ts2gd

CLI command to scaffold a new ts2gd project; not a programmatic import.

compilation (watch mode)

✓ ts2gd

✗ ts2gd --watch

Running `ts2gd` without flags starts watch mode; `--buildOnly` compiles once.

compilation (single build)

✓ ts2gd --buildOnly

✗ ts2gd --build

Use `--buildOnly` to compile all source files once and exit.

Installs ts2gd globally, initializes a Godot project, writes a basic TypeScript script, and compiles it to GDScript.

// Install globally npm install --global ts2gd # Initialize a new project cd my-godot-project ts2gd --init # Write a TypeScript script (e.g., src/MyScript.ts) import { Node2D, Input, KeyList } from "godot" export default class MyScript extends Node2D { _ready(): void { if (Input.is_key_pressed(KeyList.KEY_SPACE)) { print("Space pressed!") } } } # Compile # Watch mode: ts2gd # One-time build: ts2gd --buildOnly

ts2gd --version

Debug

Known issues

gotchaScene globals (e.g., MySceneTscn) are automatically created and exported; no need to preload

fix

Import the scene global directly (e.g., `import { MySceneTscn } from "godot"`) and use `instance()` instead of `preload()`

affects: >=0.0.0

gotchaEnums are namespaced under enum name (e.g., `KeyList.KEY_SPACE`), not global scope

fix

Use `EnumName.Property` syntax; see generated `@globals.d.ts` for full list

affects: >=0.0.0

gotchaSignals must be declared as class properties with `$` prefix and type `Signal`

fix

Declare `$my_signal!: Signal` (use `!` to avoid TS uninitialized error)

affects: >=0.0.0

breakingAutoload classes require `@autoload` decorator and an exported instance

fix

Add `@autoload` decorator to class, then `export const MyAutoload = new MyAutoloadClass()`

affects: >=0.0.0

gotcha`rpc` calls use method-chaining syntax: `this.my_rpc_method.rpc("arg")` instead of `this.rpc("my_rpc_method", "arg")`

fix

Call `this.methodName.rpc(arg)` instead of `this.rpc("methodName", arg)`

affects: >=0.0.0

breakingGodot 3.3+ is required for autoload export functionality

fix

Upgrade Godot to 3.3 or later, or avoid autoload exports

affects: >=0.0.0

gotchaTS2GD is in early beta (v0.0.36); breaking changes may occur without major version bump

fix

Lock version in package.json, test compilations after updates

affects: <1.0.0

Errors

Common errors & fixes

Cannot find name 'KeyList'

Enum namespacing; KeyList is not globally scoped

fix

Import KeyList from 'godot': `import { KeyList } from 'godot'`

Property '$pressed' does not exist on type 'Button'

Signals must be declared in class definition with `$` prefix

fix

If using a built-in signal, ensure the class extends the correct node type; for custom signals, declare `$my_signal!: Signal`

Cannot find module 'godot' or its corresponding type declarations

Missing generated type definitions; ts2gd --init or compilation hasn't run yet

fix

Run `ts2gd --init` to scaffold project and generate types, or run `ts2gd --buildOnly` to generate `@globals.d.ts`

TypeError: this.my_rpc_method.rpc is not a function

Method is not marked as remote/rpc in GDScript; ts2gd uses `@remote`/`@remotesync` decorator

fix

Add `@remote` or `@remotesync` decorator to the method

Upgrade

Version history

0.0.36latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

packagehttps://www.npmjs.com/package/ts2gd ↗