Phaser: [Phaser 3] TypeScript definitions

[jhurliman]

Opening a tracking ticket to watch for TypeScript definitions for Phaser 3.

(Edit: Please track this is #3224 - we're locking this issue for comments, that one is open)

[itajaja]

yes! I am just starting a new game, and I would like to use phaser. It would be silly to keep using v2 if v3 is already in beta, but I would love to use phaser. Are you guys planning to bundle the definitions? and if so, when?
Thanks for the amazing work 🙏

[itajaja]

just found the answer in the gantt chart

[jhurliman]

Part of the 3.0 release currently slated for Nov 17, according to the linked Gantt chart.

[clark-stevenson]

I still don't have any idea how to automate this process 👎 The most promising idea I have heard is some kind of JSDoc but at the end of the day I never had a clue on where to start and I suspect some of the "patterns" and "invented interfaces" I have seen in my time simply cannot be automated from the information that is there untyped. Manually updating the definition file gets incredibly tedious and is open to a lot of inaccuracy as projects scale.

I would love to hear anyone's thoughts on this subject.

[itajaja]

probably the best way to automate the process is to write in typescript in the first place :trollface: it also helps a lot for a very complicate software project like phaser. "Jokes" aside I think that in line of principle, the same way you autogenerate documentation, you can use it to generate ts, with the caveat that typescript definition needs to be more precise. I think jsdoc is a good way to go, and it's seems typescript already supports internally this translation: https://github.com/Microsoft/TypeScript/wiki/JSDoc-support-in-JavaScript

[photonstorm]

We are absolutely 100% automating it for V3. There is no way I want anyone stuck with the task of manually updating the defs again. So far my thinking is that I will use a custom jsdoc tag to help out when the type isn't possible to figure out from jsdoc alone.

[dentych]

Hey. I don't know if this is something that has been discussed before. But just a question/comment, partly based on @itajaja's comment 😃. Is there any reason not to switch Phaser to TypeScript? TypeScript seems like a good choice for large projects (which Phaser seems to be). This will make generation of the TypeScript definitions able to be part of the build process, which would be very easy.

I say this, because I've pretty much entirely switched to TypeScript when making JavaScript. It takes some setup time, but it's really nice to have compiler-time errors, as well as the IDE intellisense actually working.

Anyway, it's just a suggestion. I'm aware that it's quite a lot of work to change from plain JS to TypeScript, but in my opinion, it would really be helpful in the end :)

[photonstorm]

It's a phenomenal amount of work. Such a pivot, this close to release, isn't a sensible move. It's the kind of decision that has to be made before development starts (and it was, we discussed it at length on the forum, and plain JS won out)

[clark-stevenson]

Phaser 2 started as a TypeScript project back in the day! Rich was an early adopter and got some wounds from the rapidly evolving eco system and lack of tools, as well as lack of people with the skills to make PR requests.

So it is hard to be the judge of the whole history of the project. It does mean we have no real access to Phaser 3 which sucks because I also look down my nose at rawJS like it is Victorian times and consider it uncouth. 😛

[dentych]

I guess that's always a risk when early adopting something. However, I would argue that the eco system has become a lot more stable since. In the beginning when types had to be received with the typings npm package and stuff, it was very confusing and not very stable. That has gotten better now I think. It was only a mere suggestion. I like the world that JavaScript opens, I just really dislike the JavaScript language being untyped 😛

EDIT: I actually missed @photonstorm's comment.
The decision with plain JS is also entirely fair. I was just curious. Maybe in the future it can become a TypeScript project, unless it turns out annotations for def files works great 😄
Also, thanks for the prompt responses!

[photonstorm]

TS has evolved significantly since Phaser last used it. It was a hot steaming crash-prone mess back then. I've no doubt it's a lot better now.

It's still not going to happen though. The costs outweigh the benefits too much.

[dentych]

That's entirely fair. Nonetheless, Phaser seems to be a magnificent piece of work. I look forward to making games with it, and if I get good enough with the framework, hopefully be able to contribute to its development! 😄

[Katamori]

What about a separate custom branch, or even a fork for TypeScript development?

I think Phaser has already grew large enough to go on separate ways on demand.

[clark-stevenson]

I think it is a really big undertaking.

In the past, Phaser 2 never stood still. On a weekly basis for over a year, it would often take several hours to track the updating API. I jest about TypeScript, but aside from language, Rich puts in outrageous amounts of work on a weekly basis.

So even manually keeping up just the declarations without caring of the implementation inside is still a big effort. If Phaser stood still on 3.0.0 release and never had any PRs, features, issues or changes. I would love to try it! Unfortunately I can't imagine the time required to maintain it.

[photonstorm]

Trust me, 3.0 has zero chance of standing still long enough that this would be a sensible undertaking :)

[GeertJohan]

I think using plain JS might even make more sense for a game engine's internals. I suspect TypeScript will always add overhead when compiling to ES5/ES6, resulting in a less performant engine?
Anyway, having TS definitions of the public API would greatly improve my happiness as a user :smiley:
I can't find any ts definitions right now, but I understand these will be generated from the jsdoc? So probably close to 3.0 release or maybe 3.1?

[photonstorm]

There will definitely be TS defs with the 3.0 release.

[darthdeus]

@GeertJohan there is no overhead, the types are checked at compile time

Anyway, really hoping the defs come soon :( I was just about to give phaser another try, but not sure if I want to go the JS route.

[photonstorm]

Defs are on their way.

[clark-stevenson]

@photonstorm you are a busy guy right now but well done! I have no idea how you did it ❤️

[mmiszy]

Are type definitions under @types/ on npm or should I look for them in Phaser's repo?

[troyedwardsjr]

I've started generating typescript definitions for Phaser 3 using Richard's JSDoc annotations.

If anyone is interested in helping:
https://github.com/troyedwardsjr/phaser3-tsd

[mmermerkaya]

I think this issue should stay open, at least until the definitions are done.

[Majirefy]

Waiting for TS definition.

[troyedwardsjr]

Making good progress on writing my Phaser 3 typescript definition generator/transpiler.

First full build:

https://github.com/troyedwardsjr/phaser3-tsd/blob/master/build/phaser.d.ts

[troyedwardsjr]

I haven't tested everything yet but using my modified version of Antriel's official (WIP) Phaser 3 typescript definitions build, I was able to get scene properties (plugins) to work using a hacky generator by stepping through Phaser code with the browser debugger, converting any useful runtime data to JSON, writing it to disk, then converting it with a simple script, and injecting it into Antriel's build.

End result: Everything appears to be compiling in the typescript compiler so far, with code hinting, autocompletion/intellisense, ect. in VS Code (and I imagine similar editors).

Note: This is a temporary, hacky, potentially unstable solution for those who want to start building their Phaser 3 typescript projects right now while we wait on offical typescript support to be completed by Antriel and the Phaser team.

Modified build here:
https://github.com/troyedwardsjr/phaser3-tsd/blob/master/build/official/phaser.d.ts

Also created a boilerplate starter project, with definitions included:
https://github.com/troyedwardsjr/phaser3-typescript-webpack

[SrKomodo]

Any new progress on this?

[goowikns]

I can't seem to find any typings when installing Phaser through npm

[mmermerkaya]

@photonstorm Can you reopen this issue? You said that the defs will be available on release of 3.0, but they aren't, so I think it makes sense to keep this issue open until they are done.

[photonstorm]

3224 is already open. One issue about the same thing is enough.

[mmermerkaya]

It's your call, but I would keep this open, and close (and lock) #3224 as it's a duplicate. Right now people are posting the same comments on both issues, because the other one is open, and this one is the actual issue and not a question.

[mattiasflodin]

You should at the very least update the documentation on the website to reflect that there are no TS definitions available, before closing this. I decided yesterday on using Phaser, and spent a couple of hours today trying to figure out what I was doing wrong. The introductory material on phaser.io makes no indication that Phaser 3 is not mature, and when you follow the download links it tells you to do npm install [email protected]. The documentation here says "As of Phaser 2 the TypeScript definitions are found in a folder called typescript in the root of the repository." You'd assume that "as of Phaser 2" also includes Phaser 3, but apparently not.

[photonstorm]

That would be the tutorial dated 2013 talking about TypeScript 0.9.5? Agreed, it should be updated, but the clues were there.

This is closed because it's an older duplicate, no other reason. I've now linked to the current issue and am going to lock this one for comments.