Comparison to GodotExplorer/ECMAScript

[lostfictions]

Hey there, thanks for writing this! I'm giving it a shot -- attempting to rewrite one of the Godot sample games -- and I'm impressed with how well it works already.

In the interests of documentation, one thing I think might be interesting is a comparison as to how it stacks up against GodotExplorer/ECMAScript (henceforth GE-ES). Here's a few things I'm noticing:

• The most obvious difference is that GE-ES is full binding of a JS engine (QuickJS) to Godot; ts2gd is a source-to-source compiler (or transpiler). It's more comparable to something like the wonderful TypeScriptToLua project.
• Consequently, GE-ES supports ECMAScript built-ins, including methods like Math.sin() or String.includes(). ts2gd instead requires you to use GDScript equivalents. Fortunately, it provides quite thorough type definitions for them including docstrings, which eases the learning curve for users coming from JavaScript-land. GE-ES also supports instanceof -- which performs narrowing in TypeScript -- while ts2gd appears to have no equivalent (though it could probably transpile instanceof to the GDScript is operator).
• Because it binds a new language to Godot, GE-ES requires custom Godot builds; they offer prebuilt binaries on their releases page and bleeding-edge CI builds. ts2gd works with "vanilla" builds of Godot, or indeed any version that has GDScript support.
• GE-ES supports operator overloading (one of QuickJS's flagship additions over standard ECMAScript). Unfortunately, they haven't yet worked out a way to make TypeScript support them (1, 2) and instead currently require you to litter your code with @ts-ignores or as any assertions, both of which are noisy and degrade both type safety and the editor experience. ts2gd has already worked around this with methods on Vector2/Vector3 instances; while it's slightly less ergonomic, it's typesafe. GE-ES could add such methods but has yet to do so.
• GE-ES supports debugging your JS code via a VS Code debug adapter, including sourcemapped TypeScript. ts2gd has no such support as far as I can tell, though you can use the more popular and slightly more official godot-tools to debug your transpiled GDScript. In the future it might be possible for ts2gd to emit sourcemaps and allow debugging source files, in the same way TypeScriptToLua supports debugging source files via the Local Lua Debugger extension.
• GE-ES is ultimately constrained by the boundaries of tsc and TypeScript's "it's just JavaScript" philosophy; it can't take advantage of type annotations beyond typechecking. On the other hand, ts2gd, like TypeScriptToLua, leans heavily into type-directed emit; the resulting GDScript is output with type annotations. This has the advantage of potentially unlocking performance optimizations down the line.
• GE-ES supports multithreading via the Worker API, and even allows the use of npm libraries. Since ts2gd doesn't have support for ECMAScript built-ins, it can't do this. (It's worth noting that TSTL has implemented polyfills for many ECMAScript built-ins, allowing for a limited form of third-party library support; ts2gd could potentially do the same. Impressively, TSTL has even added support for Promises and async/await via Lua coroutines!)
• GE-ES naturally supports all TypeScript syntax; ts2gd currently appears to choke on some things (it seems to explode on import type, for example).

[johnfn]

holy moly, what a great write up!

as you may have noticed im on a bit of a hiatus on this project because of work, but i'm really thankful for such an in-depth analysis! hopefully i'll find some more time to work on it soon :)

BTW, i do know off the top of my head that getting import type to work is like a 2 line change, so if you ever have some spare time... 😉