cocos2d-x Documentation

Release 3.0rc2

Ricardo Quesada

April 21, 2014

Contents

What is CocoStudio 1.1 UI Editor . . . . 1.2 Animation Editor 1.3 Scene Editor . . 1.4 Data Editor . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

3 4 4 6 6 7 7 7 11 11 13 15 15 15 16 16 23 23 29 37 39

Getting Started 2.1 Download CocoStudio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2 Taking a Look at the Built-in Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Lets Build a Parkour Game 3.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2 Design the Required Game Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A Step by Step Process to Make GameMenuUI 4.1 Decide Which Kind of Widgets Shoule be Included 4.2 Put Everything You Need by Adding Widgets . . . 4.3 Set Properties and Export . . . . . . . . . . . . . 4.4 How to Use the Exported Resources . . . . . . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

A Step by Step Process to MAke CMRun 5.1 Creating Proejct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2 Scene Editor and Data Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Keep Going Indices and tables

6 7

ii

cocos2d-x Documentation, Release 3.0rc2

Contents: Contents What is CocoStudio UI Editor Animation Editor Scene Editor Data Editor

Contents

cocos2d-x Documentation, Release 3.0rc2

Contents

CHAPTER 1

What is CocoStudio

CocoStudio is a professional game development tool based on Cocos2d-x. It promises to be free of charge in an innite duration. With CocoStudio, developers can create game resources quickly and simplify most of the tedious development work with the four editors provided. They are UI Editor, Animation Editor, Scene Editor and Data Editor. These four editors cover the core process of game development by dealing with animation resources, UI interface, gaming scene and gaming data. Also, each of them has been specically designed for the best of the corresponding role in the development team and therefore allows everyone to perform his/her duties with least misuse and most efciency. In brief, CocoStudio will help you achieve high productivity and quality with low risk and cost.

Figure 1.1: CocoStudio Launcher Figure 1: CocoStudio The birth of CocoStudio was no accident. We have met so many problems when we get started with the FishJoy2 in 2012. As the Cocos2d-x didnt have any visualization tools when it came to UI appearence or animations of roles, it

cocos2d-x Documentation, Release 3.0rc2

used to take a great deal of time for programers to modify their programs to t the requirements from game deisigners. At that time, we were considering about developing a visual toolkit to help to solve these problems. Then we developed a toolkit called SP-II to support FishJoy2 at rst. Half a year later, we processed this SP-II and released the rst ofcial version of this toolkit on April 2013, and that was CocoStudio.

1.1 UI Editor

UI Editor is an editor that edits all the Graph Interfaces, used mostly by art designers. They import ready interface images into the editor and place, design, edit, joint and modify them in the light of the design scheme. Then, with edited UI resource exported, they can be used directly into the game codes. The UI Editor embraces all plug-ins of Cocos2d-x and it has extended some of them, satisfying various demands of UI plug-ins during the developing process. It is also supportive of individual image exporting, whole image exporting, UI template, UI animation and other practical uses.

1.2 Animation Editor

Animation Editor is an editor that edits dynamic game resources such as character animation, special-effect animation and scene animation. Art designers would be using it more often than other people. After importing ready image resources into the editor, they are able to put on various animation effects according to the design scheme and preview them in the editor. The editor supports key frame animation, sequence frame animation, bone animation, etc. Also, it allows for a wide range of resource optimization methods like exporting individual images or the whole image, as well as parse of Flash, PSD and Plist resources.

Chapter 1. What is CocoStudio

cocos2d-x Documentation, Release 3.0rc2

1.2. Animation Editor

cocos2d-x Documentation, Release 3.0rc2

1.3 Scene Editor

An editor for designing scene elements and game levels. With the editor, planners are able to integrate a mix of diverse game resources, including animation resources, UI resources, map resources, particle resources, image resources, audio, etc. Meanwhile, it can also be used to edit logical resources such as collisions, triggers, and controllers. Furthermore, the editor supports simulation operation, meaning that one can run the current scene in the simulator or his/her phone via wireless connection.

1.4 Data Editor

The data designers import tables of values into this editor, break down the complicated ones, and then export them as common data les such as table of attribute or data. A wide range of different data arrangements can be choosed from data manager while exporting as the editor supports index.anima Contents Getting Started Download CocoStudio Taking a Look at the Built-in Examples * Taking a Look at the Tests * Taking a Look at the Sample Demos

Chapter 1. What is CocoStudio

CHAPTER 2

Getting Started

2.1 Download CocoStudio

The CocoStudio can be downloaded at our ofcial website: http://download.cocos2d-x.org/ In this book, we offers a number of ways for you to learn about CocoStudio on your own - there are tests in Cocos2dhtml5 available, as well as sample demos in the editor. You are also welcome to take a further look at help documents at http://help.cocostudio.org/ .

2.2 Taking a Look at the Built-in Examples

2.2.1 Taking a Look at the Tests
All tests of the CocoStudios API can be found in Cocos2d-html5. For example, to know how to make a frame event with armature, you run the Cocos2d-html5 and you can see it under CocoStudio test called Test Frame Event, and the code of these tests is in the project Cocos2d-html5/samples/CocoStudioTest/ArmatureTest/ArmatureTest.js. Figure 2: CocoStudio Test - Test Freame Event Figure 3: ArmatureTest.js

2.2.2 Taking a Look at the Sample Demos

In CocoStudio, when you open the UI Editor, Animation Editor or the Scene Editor, you will nd sample demos on the beginning page. So you here you can try to open these samples, or help you get started on your own. Figure 4: Sample Demos in CocoStudio Animation Editor

cocos2d-x Documentation, Release 3.0rc2

Contents Lets Build a Parkour Game Overview * The Introduction of IronCity Design the Required Game Components A Step by Step Process to Make GameMenuUI Decide Which Kind of Widgets Shoule be Included Put Everything You Need by Adding Widgets Set Properties and Export How to Use the Exported Resources A Step by Step Process to MAke CMRun Creating Proejct * Drawing Bones * Animation Mode * How To Use The Armature In The Program * How To Callback The Functions Scene Editor and Data Editor * Scene Editor * Data Editor

Chapter 2. Getting Started

cocos2d-x Documentation, Release 3.0rc2

2.2. Taking a Look at the Built-in Examples

cocos2d-x Documentation, Release 3.0rc2

10

Chapter 2. Getting Started

CHAPTER 3

Lets Build a Parkour Game

3.1 Overview
3.1.1 The Introduction of IronCity
This is a little simple parkour game to show you how to use CocoStudio in a game. It is called IronCity, made with Cocos2d-html5 and CocoStudio v1.0.2.(CocoStudio released its latest 1.1.0 version during the writing process of this document.) The user interfaces and the animations of IronCity were created with CocoStudio. You can clone it from our github: https://github.com/yuye-liu/CocostudioIronCity IronCity consists of 2 scenes - the main menu scene, and the game scene. Its a simple shooting game. In the game scene, you can use gestures to control the CocoMan (The main role) to run, jump, stop or shoot. The goal is to run as far as possible, shoot as many monsters as you can - the higher score, the better you do.

Figure 5: Main Menu Scene Figure 6. Game Scene

11

cocos2d-x Documentation, Release 3.0rc2

12

Chapter 3. Lets Build a Parkour Game

cocos2d-x Documentation, Release 3.0rc2

Figure 7: Code Structure of IronCity The screenshot shows the structure of IronCity. We separated the sources into 3 parts. I will talk about each part in a nutshell with special emphasis on the ones that used CocoStudio. MainMenuScene.js: The beginning scene of IronCity, including a background pictures and a start button. Tap start button and it will change to the next scene: the game scene. GameScene.js: The main scene of IronCity. All the constants of resources have been dened here. The game scene has 3 layers: menu layer, play layer and gameover layer. It also controls all the collision detection for the CocoMan. Background.js: Create the background map of the game scene. Use tilemap to draw these maps and put them together into a complete background. GameOver.js: This is a UI layer. When CocoMan dies and the game scene will create the game over layer. The game over layer includes a UI that shows the score of player. The UI in game over layer is made by UI Editor, all of the 3 layers UI Editors projects can be found in the path CocoStudioIronCity/IronCityCocoStudioProject/IronCityUI .

Figure 8: IronCityUI Laser.js: Laser is CocoMans weapon. Once you tap the screen in the game scene, the CocoMan will shoot laser to the touch point. The laser extend cc.Sprite class. In Laser.js, it provides several functions, for example, add or release a laser. MenuUI.js: MenuUI is a UI layer, too. It contains 3 basic user interfaces created by UI Editor as a game menu: a blood bar, a distance score and a setting button. This is a very simple example so I will choose this MenuUI to show how to use UI Editor in next section. SettingUI.js: SettingUI is a UI layer for setting. If you touch the setting button on the game scene (setting is belong to MenuUI), it will pause the game and create the SettingUI. It can switch off or switch on the music effect, regulate the volume of music , return to the game and back to the main menu scene. Monster.js: There are two kinds of monsters in IronCity. The Monster class extends from cc.Node get the functions of generating, destroying, moving the monsters and playing the animations of monsters. The animations of monsters is created by Animation Ediotr. But they are just some picturess replacement work, they dont use any armatures here. So I dont talk too much about this animations here. Later we will see a complete armature animation in next section. Player.js: Player is a class extend from cc.Layer. Player includes an armature called imManArmature. This is CocoMans armature. The major functions of Player is to load and play 7 animations of CocoMans armature. Im going to talk about the running anmation to show you how to build an armature by Animation Editor.

3.2 Design the Required Game Components

We are going to show how to build users interface and animations through UI Editor and Animation Editor. We didnt use Scene Editor or Data Editor in the IronCity, you can get help from help documents if you need it. We designed and created 3 menus and 9 animations by CocoStudio in IronCity. If you cloned the remote on the github site I just mentioned about, you can nd all of these CocoStudio projects in the folder IronCityCocoStudioProject. The 3 menus are called GameMenuUI, GameSceneOverLayer, GameSceneSetMenu. They refer to the 3 layers in the game scene of IronCity. And the 9 animations like CMRun or CMRunJump are used to be the animations 3.2. Design the Required Game Components 13

cocos2d-x Documentation, Release 3.0rc2

for CocosMan. In next section, I will choose the GameMenuUI and CMRun to show how to use UI Editor and Animation Editor.

Figure 9: CocosManAction

14

Chapter 3. Lets Build a Parkour Game

CHAPTER 4

A Step by Step Process to Make GameMenuUI

4.1 Decide Which Kind of Widgets Shoule be Included

Firstly, decide what is needed in the UI. The GameMenuUI of IronCity is easy to draw. Here I want a blood bar, distance score and setting button. Id open the CocoStudio, choose the UI Editor, create new project from the le.

Figure 10. Imagination of IronCity

4.2 Put Everything You Need by Adding Widgets

Figure 11: UI Editor This is a screenshot of UI Editor. I have put my resources into the editor by adding widgets. The yellow parts are comments. The tools provide 8 ways to help you align and 2 ways to rotate. You can set up the resolution of your UI Layer by canvas, which offers several different resolutions. You can see a normal button on the left side of canvas. This button changes UI Editor from normal mode to animation mode. The animation part is almost the same as the animation Editor, and Id be talking about this in Animation Editor.

15

cocos2d-x Documentation, Release 3.0rc2

There are 14 widgets in the widgets toolbar. I will introduce some of them later. All of the widgets can be dragged into the main render. If you hold down space on keyboard, you can move your canvas on the main render by your mouse. Some of shortcut keys in CocoStudio is similar to that in PhotoShop. Then you pull the picture resource from the Resources Menu into the Properties. In this case, I dragged a bloodBar.png to the my bloodBars texture. The resources menu supports importing or dragging a .psd le, but the names of the resources should be English. Here I have added all widgets I need and set up the pictures from resources. The object structure shows the hierarchy of the layer, but that is not the actual order in the game. In Cocos2d-x and Cocos2d-html5, we use Zorder to represent the hierarchy of the sprites, while in UI Editor, it is called render layer, and can be found under Properties Menu of every widgets. Figure 12: Drag Resource into the Texture

4.3 Set Properties and Export

The nal step is self-expalnatory. I have everything prepared for my GameMenuUI. Just click export projects in the File. Most of the time, we use the default setting for exporting. Dont forget to set the properties of the widgets before exporting. For example, if you didnt tick the touchable in the properties of Panel, everything belongs to Panel cannot be touched, even if the child node has ticked the touchable in its own property. Figure 13: Set Properties Before You Export

4.4 How to Use the Exported Resources

Figure 14: Put all of the expoerted les into your game resources After exporting, you will see a number of les in the export folder of your CocoStudio project. Put all of them into your game resources. There would also be a json format le. This is a JavaScript Object Notation le, a kind of data exchange language. All of your settings in the UI Editor have been saved in this le. Its not difcult to read a json format le. So sometimes you may gure out your problems through this le.

16

Chapter 4. A Step by Step Process to Make GameMenuUI

cocos2d-x Documentation, Release 3.0rc2

4.4. How to Use the Exported Resources

17

cocos2d-x Documentation, Release 3.0rc2

18

Chapter 4. A Step by Step Process to Make GameMenuUI

cocos2d-x Documentation, Release 3.0rc2

4.4. How to Use the Exported Resources

19

cocos2d-x Documentation, Release 3.0rc2

Figure 15: Exported JSON format le Figure 16: MenuUI.js Lets see how to use the exported resources in IronCity. In IronCity, we arranged all the resources constant to another le.(GameScene.js) Here is the Layer Menu UI and its initial function. (MenuUI.js in IronCity Cocos2d-html5 version.) *this.addWidget( cc.UIHelper.getInstance().createWidgetFromJsonFile(Json_IronCityUI_1));* createWidgetFromJsonFile() is the way to read the json le into your game. In the MenuUI, we have a setting button , blood bar(progress bar), distance score(atlas label), and they all need interaction during the game. So we get these widgets by the getWidgetByName()function as in the pictures. Remember that the names of the widgets can be found in your object structure. Different widgets will have their own interfaces to be called in the program. For example, you use setPercent() to set the rate of a progress bar, and setStringValue() for the atlas label to change the value. All widgets can add a addTouchEventListener() to listen the touch event. In IronCity, we arranged all of the resources constant to another le. Try to learn more about from the CocoStudio test inside Cocos2d-html5.

20

Chapter 4. A Step by Step Process to Make GameMenuUI

cocos2d-x Documentation, Release 3.0rc2

4.4. How to Use the Exported Resources

21

cocos2d-x Documentation, Release 3.0rc2

22

Chapter 4. A Step by Step Process to Make GameMenuUI

CHAPTER 5

A Step by Step Process to MAke CMRun

5.1 Creating Proejct

We are going to create a running animation for the cocoMan. First, same as the GameMenuUI, I built a new project named running, then I dragged all of my resources into Resources Menu.

Fiture 17: Animation Editor The picture is the screenshot. The default mode is in the Posing Mode, and you can change it into Animation Mode with the button in the upper left corner. Next, lets nd out how to create a complete armature in Animation Editor.

5.1.1 Drawing Bones

To create a whole armature, each picture of the bones should be complete.

23

cocos2d-x Documentation, Release 3.0rc2

A good design of an armature is important. In IronCity, we divided the cocoMan into 6 parts. We created the body parts by using 2-4 bones and assembled them when they were nished.

Figure 18: Create Bone in Animation Editor So, in this case, as the picture shows, we put all of the pictures into the main render. This is a right leg, consisting of 4 skeletons: thigh, shank, knee and foot. Then you can draw the collision region part in the HitBox. Here I am just showing you one option, but we actually did it with another way. Because the more bones and its collision regions you create, the lower performance it will be on the browser. Thats why we didnt use it. If you still need it, try to nd the sample called TestColliderDetector in CocoStudio Test. After combination, we now have a whole right leg on the main render. Its time to create bones now. 5 steps to create an armature: 1. Choose create bone mode. 2. Draw bones. 3. Disable create bone mode. 4. Bind pictures to bones. 5. Bind children bone to their parents.

24

Chapter 5. A Step by Step Process to MAke CMRun

cocos2d-x Documentation, Release 3.0rc2

Figure 19: Step 1-2

Figure 20: Step 3-4 Figure 21: Step 5 After all the work, I have created all parts of the cocoMan and nally assembled them just like playing Jigsaw. Dont forget to bind parent bones when it comes to the joint. This pose is going to be the start of running animation. All of the other poses will be extended or copied from this basic armature. Next section we are going to create animations. Figure 22: Repeat The Step 1-5 to Build a Whole Armature

5.1. Creating Proejct

25

cocos2d-x Documentation, Release 3.0rc2

26

Chapter 5. A Step by Step Process to MAke CMRun

cocos2d-x Documentation, Release 3.0rc2

5.1.2 Animation Mode

Figure 23: Animation Mode Change the mode into animation (Press the button on the left upper corner.) The interface of animation mode in UI Editor and Animation Editor are almost the same, as well as their usages. The timeline is the core of creating an animation. If you know anything about ash or spine, it should be easy to get started. There are many frames in the timeline. Each frame represents a time point for the armature. Using rotate or shift button to set up the status and poses for each bone of the armature on the key frames, in this way you can create an animation. Figure 24: Key Frames of CMRunFigure These are the key frames of running animation. The Frame 40 is missing because that is identical with Frame 0. In this way, you can make your animation coherence when it comes to a loop(tick the Loop). Pressing play button in the timeline can show the animation. You can also modify the fps to control the speed of your animation

5.1.3 How To Use The Armature In The Program

Figure 25: Create Armaute and Run We have nished the armature and animation. Youll nd 3 les in the export folder after exporting(default way). The ExportJson le is like the json le, which is rather informative. The function CMRunning() is a simple way to create an armature and run its animations.(Player.js) Using cc.ArmatureDataManager.getInstance().addArmatureFileInfo(Json_CMRun)to read the resources from the path, just like the UI Editor. cc.Armature.create(CMRun) will try to create an armature called CMRun from all the ExportJson le. CMRun is the name of your project, but you can also try to replace all the CMRunin the ExportJson le, this is a fast way to change the armatures name.

5.1. Creating Proejct

27

cocos2d-x Documentation, Release 3.0rc2

28

Chapter 5. A Step by Step Process to MAke CMRun

cocos2d-x Documentation, Release 3.0rc2

armature.getAnimation().play(Running) will begin to look for the animation named Running in this armatures ExportJson le. This name can be set in the animation list from Animation Editor. You can edit it in ExportJon le as well.

5.1.4 How To Callback The Functions

There are 2 ways to call back a function for the armatures. One is setMovementEventCallFunc(), the other is setFrameEventCallFunc().

Figure 26: How to Set Callback Functions

5.2 Scene Editor and Data Editor

5.2.1 Scene Editor
Figure 26: Scene Editor Sample: RPGGame on CocoStudio v1.1.0 The picture is the sample called RPGGame on the start page of Scene Edtior. The interface of Scene Editor is similar to that of UI Editor. And the general operation is the same story for the UI Editor. You add the resources, drag the widgets, set the properties and export the project. Here are some introduction to show the features. Figure 27. Play, stop and connect to device button Figure 28: Connect Device Play, stop and connect to device button: These three buttons can be found on the right side of the Canvas. Single click play, youll get a win32 program running, and that is what you have been editing in Scene Editor.stop button would close the application. And the last button is named connect to device. It can start a server, which allows you can visit the IP address given to help you run the scene on other device, such as html5 or mobile phones. Sprite: CCSprite in Cocos2d-html5.

5.2. Scene Editor and Data Editor

29

cocos2d-x Documentation, Release 3.0rc2

30

Chapter 5. A Step by Step Process to MAke CMRun

cocos2d-x Documentation, Release 3.0rc2

Figure 29: Names of the widgets in Scene Editor Armature Componet: CCArmautre in Cocos2d-html5. Dragging your armautre resources (usually a ExportJson format le built by Animation Editor) into the Aramture File would load the armature to your Scene. Then you can choose which animation to play in the Animations List.

Figure 30. Armature in the sample: Fight Scene UI: Similar to the Armature Component. You can add your UI resources into the UI widgets. The UI resources can be built by the UI Editor. Map Component: Drag your map resources into the Map Component. The map resources may be a tmx format le

5.2. Scene Editor and Data Editor

31

cocos2d-x Documentation, Release 3.0rc2

which is exported by the TileMap. Particle Component: Particle resources can be built by Particle Designer. The Particle Component can help to add your particle resources to your scene.

Figure 31. Particle Component properties Audio: The audio in Scene Editor supports mp3 and wav format. Add your audio by dragging the Audio widget.

Figure 32: Audio properties Custom Property: Custom Property is related to Data Editor so Ill talk about it later. Figure 33: Scene Editor Test The picture shows the SceneEditorTest in Cocos2d-html5. This is a test sample for the FishJoy2 in the Scene Editor start page. Using createNodeWithSceneFile() to create a CCNode from the exported resources by Scene Editor. As all of the widgets in Scene Editor can set a Tag property, you can get the widgets through getChildByTag() from their parent node. So there is nothing difculty about using the exported Scene Editor resources. Try to learn more from the CocoStudio Test if you meet any kind of questions. Figure 34: Running the SceneEditorTest shows the image you edited in the Scene Editor

5.2.2 Data Editor

Figure 35: Data in the Excel Figure 36: Data Editor Data Editor can import template table from Excel or CSV les. The data designer can edit these data in the Data Editor and then export them to a Json format le. And the exported Json le can be used in the Scene Editor as

32

Chapter 5. A Step by Step Process to MAke CMRun

cocos2d-x Documentation, Release 3.0rc2

5.2. Scene Editor and Data Editor

33

cocos2d-x Documentation, Release 3.0rc2

34

Chapter 5. A Step by Step Process to MAke CMRun

cocos2d-x Documentation, Release 3.0rc2

a custom component. Then you can use the custom component in your code. See how to use custom component in SceneController from Components Test. Contents Keep Going

5.2. Scene Editor and Data Editor

35

cocos2d-x Documentation, Release 3.0rc2

36

Chapter 5. A Step by Step Process to MAke CMRun

CHAPTER 6

Keep Going

If you want to learn more baout CocoStudio, visit the following websites for more details: The Ofcial Website: *http://www.cocostudio.org* The Ofcial Forum: *http://www.cocos2d-x.org/forums/24*

37

cocos2d-x Documentation, Release 3.0rc2

38

Chapter 6. Keep Going

CHAPTER 7

Indices and tables

genindex modindex search

39