Where to start to get to know the APIs?

Topics: Sample Code and Demos
Feb 14, 2014 at 8:08 AM
Cocos2D-XNA is not really blessed with comments in the code :-)
Documentation is also rare.

If I'm new to the framework, what is the closest framework to look at for starters:
  • Monogame
  • Cocos2D
  • The Cocos2D Xamarin C# bindings
  • Cocos2D-X

I know there is the Angry Ninjas example. But that is pretty complex. There are many tutorials for the other frameworks, starting with very simple games. So I'm wondering which ones are easiest to translate to Cocos2D-XNA?
Feb 14, 2014 at 9:06 PM
How about if we don't approach this as "how do I learn the framework," but rather "how will cocos2d-xna work with my game idea."

Do you have a game already designed? If not, please spend lots and lots of time designing your game. Draw out the screens as you see them working, the art does not have to be perfect. Use stick figures. Use Visio if you have it. Print paper and mark it up regularly. Making a game is very creative and can be exhaustive, even before you write code. If you have the game idea clearly thought out before taking on the framework then you will be much happier. You will feel more accomplished because you will not feel as if you are losing time learning the framework.

The framework is hugely complex yet simple to implement. There are VSIX extensions to Visual Studio that make the startup of your project very quick.

It all starts with scenes. You write a scene that is composed of CCLayer implementations. This takes the form of buttons, sprites, menu items, everything like that. You paste layers atop eachother to make your game presentation.

If your game is a touch game, then you will receive touch notifications in your layers that are registered for touch. This is done by simply setting TouchEnabled to true on the layer and then telling the framework how you want touches. You can get them one at a time, or you can get all of them at once, as in a multi-touch game. You will always get all of the touches, you just will get them either as a serial stream or as a chunk of all touches happening at time (t).

If you are new to games written with XNA then you will need to familiarize yourself with the core concepts in XNA. One such concept is synchronized game time. Each update will give you a new game time. This game time is very important because it will adjust when your game is in the background, paused, or slows down. There are two methods in your game and its game components that are invoked in each game iteration. These methods are draw() and update(). The game iteration is a cycle of time, or a "Time Slice" as it was called long ago. Think of your game engine as a giant cooperative multitasking engine and each time slice it must handle processing of all the tasks that it can fit in the time slice duration. The duration of your time slice is determined by your framerate. Games used to be at 30 fps, but now they are 60 fps. That's 1/60th of a second for each update + draw iteration, or time slice as I called it.

Scenes are displayed using CCDirector. CCDirector.SharedDirector.RunWithScene(myScene) is the starting point of your game. Once you run with a scene, your game is displayed and you are off to the race. In your first scene you will run more scenes using CCDirector::PushScene() and PopScene(). As you guessed already, scene management is with a stack (like HyperCard from Apple so very long ago). You can do advanced stuff like popping down to a specific index in the scene stack, but you will likely not do that any time soon.

Layers, Sprites, etc., all inherit the core class named CCNode. Your scene is composed of one or more CCNode instances. You can make your own nodes or use the nodes provided by the framework. A nice trick is to use a generic CCNode as the parent of some scene objects that appear and disappear in unison. That way you can set the visibility of the parent CCNode and it will affect those children you want to manage.

Nodes are placed in the scene using their Anchor Point. The AnchorPoint is the position of the (0,0) coordinate system in that node. A node that is anchored on (0,0) is anchored on its lower-left corner; whereas (1,1) is the upper right, and (1,0) is the lower right, and (0,1) is the upper left. The center anchor is (0.5, 0.5). You can use arbitrary values too such as (0.25, 0.89). This point is used to handle all transform operations, including scale, skew, and rotation. Be mindful of the anchor point.

Next there is ZOrder. The framework is 2D drawn in a 3D orthographic projection using a billboard. The nodes are drawn in ZOrder, where you define any z value that is on I(-inf, +inf) (integer negative infinity to positive infinity). As the nodes are drawn, each node's children are drawn in the order of their Zorder, which is relative to the parent - always.

You draw images using textures that are just texture maps on the GPU rendered on a u,v projection to a set of triangles (facets) that are drawn using your hardware GPU. CCSprite is where you start with simple image (texture) drawing. You can load a single image into a sprite (new CCSprite("myFoo")) and draw it by adding it to the scene and setting the position (mySprite.Position = new CCPoint(5,5)). More advanced drawing of sprites will make use of sprite sheets and frames. These concepts are better reserves for performance improvement of your animations and game interaction. You can safely draw less than 50 sprites on a single scene and make the active (spin, skew, etc).

More advanced concepts are content management, building shaders, 3D model integration, ortho and iso tile map integration, deployment to console devices, game pad integration, Android copy protection, etc.

There is no good source of documentation yet. We are all volunteers and have yet to receive any donations to the project, so we are forced to spend our time in our paying jobs first. There are some xamarin tutorials on using cocos2d-xna. Remember to always use the Cocos2DXNA repository from our group and not any other forks. We also have a version of MonoGame forked into our GitHub account that we know to work well with the framework. All of these sources are compiled into the NuGet packages found on http://nuget.cocos2dxna.com

Use the forums for the best results with the framework. You will get a response. I guarantee it.
Jun 10, 2014 at 8:50 PM
That was a super long and informative post that did not answer the OP's question... Which happens to be the same question I have. I have developed multiple games in XNA and SharpDX. I am interested in using this framework for my next game but, as the OP said, there are no notes in the code and nothing to indicate while coding what a specific function does. Short of going to the source code (or simply guessing/trial and error) there is no way for me to know what a function does.

So as the OP was trying to find out, where is the best place to get documentation on the functions Cocos2D-XNA?
Jun 10, 2014 at 9:17 PM
The super long and informative post is an attempt to help you get started.

There are many samples in the 'tests' section of the repository. In there you will find examples of every thing you want to do.

Outside of those resources, there is no official documentation for cocos2d-xna.

There is a sample game available Angry Ninjas. This can be downloaded from GitHub (GitHub.com/Xamarin/AngryNinjas). That game was a cocos2d-iphone game that we converted to cocos2d-xna.

The framework models the concepts from cocos2d-x. You can purchase a cocos2d-x book and learn all about how cocos2d works. That will get you going in understanding the core concepts.

If you come to this framework with the attitude that we should be grateful for you selecting it, then choose another framework. We are all volunteers and maintain this framework when we have time to do so. This framework covers nearly every platform you can imagine and can get your game onto over 90% of the worlds computing devices. We all work very hard to keep it stable and working on those devices. We don't have a lot of time available to write books and online tutorials on how to use it.

To be more specific to "answer the OP's question" - the best place to find out how to use cocos2d-xna is google and the Visual Studio extensions and the framework tests.