Phaser: Generic TypeScript definitions

[Patrick-Sachs]

We're constantly trying to make Phaser 3 better

Currently Phaser makes heavy usage of the "any" type for user defined types.
(e.g. Phaser.GamesObjects.Group#create returns "any" instead of what the Group actually contains).

I'm very new to Phaser, but to me this approach seems more sensible:

// The = assigns a default generic, not making this a breaking change.
class Group<T extends Phaser.GameObjects.GameObject = Phaser.GameObjects.GameObject> { 
  constructor(scene: Phaser.Scene, children?: T[] | GroupConfig | GroupCreateConfig, config?: GroupConfig | GroupCreateConfig);
  // [...]
  children: Phaser.Structs.Set<T>;
  // [...]
  create(x?: number, y?: number, key?: string, frame?: string | integer, visible?: boolean, active?: boolean): T;
  // ... and the rest of the functions/properties
}

This provides me as a developer with a way better experience.

I can for example have my Phaser.GameObjects.Group<MyGameObjectType>, that returns a MyGameObjectType when calling its create function.

[Optional] Do you want to help provide this feature?

Certainly. I'll look into this once I find some time. Never worked with JSDoc or a TypeScript definition generator before though.

Let me know if this is something Phaser could use or if I misunderstood how Groups should be used and I'll look into updating some type definitions.

[G-Rath]

I'm keen to help with this as well, but not sure the best place to start :/

[dgreene1]

I’d also be interested in helping. I think the most sustainable approach would be if the maintainers were open to gradually migration the codebase to TypeScript (as opposed to relying on the jsdocs). Does anyone know if they would be interested in a migration to TypeScript?

I’ve found that it’s much easier to keep the function signature accurate if the code itself requires the types to be accurate. To put it another way, with JSDocs, the documentation tends to get out of sync easily (like with #4364).

[G-Rath]

@dgreene1 @photonstorm would be the one to talk to about that, but from my understanding, he perceive any value in TypeScript, and so has no interest in migrating to it when the JS + JSDoc works just fine.

As it is, there is a lot of refactoring going on with the documentation, which is why there are a number of object types being used instead of proper interfaces.

I'm currently working on rewriting the TypeScript parser to support events, and would welcome a second pair of eyes. Feel free to flick me a message on the Phaser slack if you're interested :)

[photonstorm]

Going to close this issue off, as since it was opened I have created type defs for every single custom object in the game. If you find any errors with them, please open those as separate issues (or even better, fix them in a PR!) but I'm happy that I've covered everything, so there are no longer 'any' globals left where the configuration is known.

[PatrickSachs]

@photonstorm That sounds great! Thanks for the work put into this.

However, a quick search for some classes that could espeically need generics like e.g. Group(which typically - at least in our project - holds objects of similar types) shows that these types did not recieve generic type definitions.
Is there a specific reason for this?

[photonstorm]

Where suitable we added Generics. Group isn't a good fit for them as Groups can hold _anything_ and any combination of those "anythings" too. Phaser 4 is being written in TypeScript, so we can address it from the ground-up, but no further changes (unless to fix definitions bugs) will be made to v3.

[PatrickSachs]

A generic can also hold different types:

type MyUnion = MyGameObject3 | MyGameObject4;
type MyGroup = Group<MyGameObject1 | MyGameObject2 | MyUnion>;

is a valid generic type constraint. Since the user would specify the generic type upon creation type safety would in this case be ensured by the compiler.