(another) Cocos2d-js TypeScript Definitions Repo

I searched around for a good set of cocos2d-js TS definitions, but everything I could find looked abandoned. I’ve created my own repo here for anybody to use:

If there is already an active repo, please let me know. There’s no need to re-invent the wheel. Otherwise, I will continue to maintain this, and hopefully others will use it and help me improve what’s there (this is my first TS project, so there’s bound to be some weird stuff going on).

I will be shipping a small game written in TS, using cocos2d-js in the next few months, and what is defined here so far was done on an as-needed basis. Still, most of the base nodes, sprites, layers, labels, actions are all there.

Also, this is based off cocos2d 3.9. Anything marked as deprecated has been purposely left out!!

6 Likes

how do i used this? sorry just a noob here… :relaxed:

Download it (obviously), just getting everything as a zip file is perfectly fine if you don’t want to do a pull request. If you downloaded the zip file, unzip it wherever you want. I keep the library at the root of my project folder.

The main header file is located at “cocos2d/cocos2d-lib.d.ts”. Include that as a reference in your TypeScript files that refer to Cocos2d objects. The way Cocos2d-js implements classes, while clever, is still an inelegant hack and not completely compatible with TypeScript’s way of implementing classes (which itself is also kind of hacky, but there’s really no elegant way to do this in JS). So if you want to subclass any Cocos2d-js class, you have to remember to call the Cocos2d class’ ctor method in your custom class’ constructor. Here’s an example (disclaimer, if there are errors in the code below, I don’t care):

namespace example {
  export class MyCustomNode extends cc.Node {
    public constructor() {
      super(); // <-- this doesn't really do anything
      this.ctor(); // <-- this actually calls cc.Node's constructor, make sure it gets called only ONCE
    }
  }
}

Finally, and maybe this should have been first, you need to be familiar with TypeScript and how to set up a TypeScript project. Personally, I do all of my cocos2d-js development using JetBrain’s WebStorm and their Chrome debugger extension. This makes developing with TypeScript fairly easy, although the compilation process seems very slow. I don’t know if this is because the TypeScript compiler is slow, or if WebStorm is slow, or both (I’m guessing it’s both).

If you have any questions, just let me know and I can help you get started.

1 Like

wow thats alot of information hehe
but ill study it on my own… il just ask if i have question, thanks man… :smiley:

Awesome, I was looking for a more up to date TS-Definition for Cocos2d-js, most of them were abandoned as you noticed, glad that I came across your post.
Any plans to keep it up to date with new releases??? is it 3.10 friendly already?
Tks for the hardwork BTW.

Short answer: I think it’s 3.10 friendly but I’m not sure.

Long answer:
I will do my best to keep stuff up to date. Unfortunately, I only have the time right now to add/fix what’s there based on the needs of the game I’m currently developing, so if you do use this expect a lot of stuff to be missing, and sometimes even an error or two here and there.

Once the game is done, I’d like to go in and fill out what was left out. As of right now, the definitions are mostly written against 3.9 (others have contributed as well, but I’m not sure what version of cc2d they used), but ideally it will keep up with the latest version. Also, anything that is marked as deprecated has been purposefully left out, and if people want to use deprecated features they can extend the definitions locally. So I encourage you to use it, but consider it still a work in progress. If you find anything that is missing or incorrectly defined (which you most likely will), please feel free to add/fix it, and I will merge your changes back into the main branch.

Good luck!

Sounds good,
I’ll start working with it, and I’ll pull request if I think I found something fishy/out of place.
Like they say, help me, to help you to help me…

Tks again for getting the ball rolling.

I definitely appreciate the work you’ve put into this, thanks.

However one thing I notice right off the bat is that cc.Sprite constructor won’t take a SpriteFrame? It insists on taking a string. However in sprites.d.ts on line 425 the big comment does explain that a spriteFrame is valid but that isn’t reflected in the TypeScript.

If I get time later in the next few weeks I’ll definitely put this to proper use.

If you find errors like that, feel free to fix them and I’ll merge them back into the codebase.

I haven’t put any time into the typescript definitions lately because I had to switch my game over to C++, which is taking up all of my time. Once my game is done (early summer), I’m going to go back and properly fix up the TS definitions repo.

If I get the chance I’ll happily do that.

But just out of interest, why are you switching back to C++?

I wouldn’t say there’s any single reason why I switched to C++, just multiple smaller reasons that eventually came to a tipping point. I could go on, but I’ll sum them up here:

  1. When my game would crash in JavaScript (some unhandled exception), it would usually just kinda hang and not respond to input. That makes me nervous, because it’s not an experience that users are immediately familiar with. When an app crashes to your home screen, people automatically know exactly what happened. It’s not good, but it’s understandable. Hanging and not responding to input/touches is a far worse experience IMO.

  2. I wanted the complete platform native experience. That means GameCenter login, iOS achievements and leaderboards, etc … That rules out SDKBOX, because while they do support things like achievements and leaderboards, it’s all 3rd party stuff. No thanks. So in order to do all that stuff, I’d have to write it in Obj-C and wire it back up to my JS using spidermonkey. No thanks x100.

  3. Eventually I would like to release my game(s) on Steam. As much as I love Cocos2d, it doesn’t really seem treat PC development as a first class citizen. The types of things you need to support in order to not get destroyed in Steam reviews requires significant amounts of extra work (e.g. switching between multiple resolutions with a menu setting change). In order to accomplish this, I’m going to have to study how some other developers have successfully done it. I do not want the added complexity of trying to get this working with the JS version.

I really like cocos2d-js, I’m much more productive using that than the C++ version. But I feel like I’ll be using cocos2d-js (and Cocos Creator especially) for rapid prototyping, and C++ for the finished product for the foreseeable future.

1 Like

Thanks for this, something to think about. #2 in particular I hadn’t thought about and might affect me.