output.html

<p><embed src="images/cover_no_badge.pdf" /></p>
<h1 id="about-this-book">About this Book</h1>
<p>Thanks a lot for purchasing a copy of <em>Learn 2D iPhone Game Development with SpriteBuilder, Cocos2D and Swift</em>. Over the last one and a half years I’ve enjoyed working with <span>SpriteBuilder</span> and <span>Cocos2D</span> while creating various tutorials for <a href="makeschool.com" class="uri">makeschool.com</a>.</p>
<p>Why did I decide to write this book? While writing tutorials, I discovered my passion for diving into details of the newly designed <span>Cocos2D</span> 3.0 API and making my acquired knowledge available to a wide audience - many readers have reached out to me, pointing to awesome projects that they have built based on our tutorials.</p>
<p>After this initial success I created the first version of the official documentation for <span>SpriteBuilder</span> and <span>Cocos2D</span>: <a href="https://www.makeschool.com/docs/#!/cocos2d/1.2/overview" class="uri">https://www.makeschool.com/docs/#!/cocos2d/1.2/overview</a>. As a developer who has often struggled through adopting new frameworks, I truly believe that good documentation is essential for the success of a product for software developers.</p>
<p>This book fits neatly between the documentation and the tutorials we provide on <a href="makeschool.com" class="uri">makeschool.com</a>. It covers many aspects of the frameworks in depth while providing you with a practical step-by-step guide on building an iPhone game that is available on the App Store.</p>
<p>I hope this book helps you getting started with building amazing games!</p>
<h2 id="who-this-book-is-for">Who This Book Is for</h2>
<p>This book should be ideal for intermediate to advanced developers that have previous experience with any object oriented programming language.</p>
<p>This book does not teach programming in general, or the <em>Swift</em> programming language from scratch! However, I don’t assume you have any previous knowledge in game programming.</p>
<p>Besides that, this book focuses strongly on <span>SpriteBuilder</span>, <span>Cocos2D</span> and 2D game programming concepts.</p>
<p>If you have experience in other programming languages, you will easily be able to pick up Swift as you read through this book. Every once in a while we will also discuss individual language features in more detail.</p>
<p>If you want a formal introduction to the Swift programming language, Apple’s book is the best reference: <a href="https://itunes.apple.com/us/book/swift-programming-language/id881256329?mt=11" class="uri">https://itunes.apple.com/us/book/swift-programming-language/id881256329?mt=11</a></p>
<h2 id="what-this-book-covers">What This Book Covers</h2>
<p>This book covers most of the core features of <span>SpriteBuilder</span> and <span>Cocos2D</span>, as well as many concepts of 2D game programming. In many chapters I discuss details about the <em>Swift</em> programming language and also dive into aspects of good code design.</p>
<p>By reading this book you should get a very good idea of the <em>big picture</em> of 2D game development for iOS.</p>
<p>One large topic is not covered in this book: the <span>Cocos2D</span> physics engine. I decided to leave it out, because it is a fairly large topic that is already very well covered through Steffen Itterheim’s <em>Learn SpriteBuilder for iOS Game Development</em> book. We also have an extensive physics based tutorial on the Make School website: <a href="https://www.makeschool.com/tutorials/getting-started-with-spritebuilder/" class="uri">https://www.makeschool.com/tutorials/getting-started-with-spritebuilder/</a>.</p>
<p>I promise, after reading this book you will easily be able to pick up the physics features of <span>SpriteBuilder</span> and <span>Cocos2D</span> through our tutorial or the official documentation.</p>
<p>Here’s a breakdown of the entire book by chapters:</p>
<p><strong>Chapter 1 - About this Book</strong>This chapter discusses the structure of the book. It introduces different conventions and gives advice on how to get the most value out of the book.</p>
<p><strong>Chapter 2 - Introduction to SpriteBuilder and Cocos2D</strong>Throughout this chapter you will build a first very simple game and learn about essential Cocos2D, SpriteBuilder and general 2D game programming concepts such as scene graphs, code connections and bounding boxes.</p>
<p><strong>Chapter 3 - Asset Handling and Basic Game Mechanics</strong>In this chapter you will start building the “Falling Food!” game on which you will work throughout the rest of the book. Chapter 3 will teach you all about asset handling with SpriteBuilder and Cocos2D. Learn how to integrate sprites and audio assets into your games. You will also learn how to use the update loop to implement object movement.</p>
<p><strong>Chapter 4 - User Interaction</strong>Learn how to implement a drag and drop mechanism. You will also implement the core game mechanic of the game: catching objects. Since this game does not use the physics engine you will learn how to implement physical behaviour. You will also get to know details about Cocos2D’s touch handling API.</p>
<p><strong>Chapter 5 - Scene Graphs, Node Transforms and State Machines</strong>Learn how to incorporate a state machine into game development. You will also get to know details on affine transformations and how they are used to in Cocos2D to implement node hierarchies. Lastly you will learn about the rendering order in Cocos2D and how to use it to create a 3D feel in your 2D game.</p>
<p><strong>Chapter 6 - User Interfaces and Implementing Multiple Game Modes modes</strong>The largest chapter in the book. Learn how to implement a level select screen using a scroll view. Learn how to structure your game to support multiple game modes - without duplicating code. This chapter covers a variety of topics in UI programming and game programming patterns.</p>
<p><strong>Chapter 7 - Persisting Highscores</strong>A brief chapter that explains how to build a simple highscore system with NSUserDefaults.</p>
<p><strong>Chapter 8 - Effects and Animations</strong>Learn how to use the powerful CCEffects API to add lighting effects to your game! You will also learn how to create particle effects. Dive deeper into SpriteBuilder’s and Cocos2D’s animation toolbox and polish the “Falling Food!” game.</p>
<p><strong>Chapter 9 - Where to Go from Here?</strong>This chapter wraps up your learning experience. Find out about additional resources on SpriteBuilder and Cocos2D.</p>
<h2 id="about-the-author">About the Author</h2>
<p><span>l</span><span>0.20</span> <img src="images/Chapter1/benji.png" alt="image" /></p>
<p>Hi! I’m Benjamin. I have four years of development experience on the iOS platform and two years of experience with Cocos2D. I have written the original SpriteBuilder and Cocos2D documentation as well as many successful tutorials on makeschool.com. I regularly give talks on iOS development topics and love teaching passionate developers at Make School. You can find me on Twitter (@benjaminencz) or simply reach out to me via email (me@benjamin-encz.de).</p>
<h2 id="how-to-read-this-book">How to Read This Book</h2>
<p>I recommend to read this book in order when you are reading it for the first time. In Chapter 3 we start working on a game that we complete throughout the book - adding features chapter by chapter. By building this game you will learn about <span>SpriteBuilder</span> and <span>Cocos2D</span> concepts and see them unfold in an actual project.</p>
<p>Once you revisit this book you will have an understanding of how the project evolves throughout the chapters. Then it will be easy to jump into individual parts of the book and use them as a reference.</p>
<p>If you already know the basics of <span>Cocos2D</span> and <span>SpriteBuilder</span> you can jump directly to Chapter 4.</p>
<h2 id="conventions-in-this-book">Conventions in This Book</h2>
<p>This book uses a few conventions to make reading it easier.</p>
<h3 id="info-boxes">Info Boxes</h3>
<p>Whenever I provide additional details on a topic that we just discussed, you will see a special info box:</p>
<p>[An info box] This information is interesting, but not essential.</p>
<h3 id="action-required">Action Required</h3>
<p>This book is very <em>hands on</em>. Whenever you are required to perform some sort of action, you will see a gray bar as an indicator:</p>
<p>Follow the instructions provided in these blocks!</p>
<p>The goal is to clearly separate the parts of the book that explain topics from the parts that require you to do something.</p>
<h2 id="source-code">Source Code</h2>
<p>All the source code shown throughout this book is available on a repository on Github: <a href="https://github.com/SpriteBuilder-Book/Code" class="uri">https://github.com/SpriteBuilder-Book/Code</a>.</p>
<p>In that repository you’ll find one project for each chapter in this book. Each project contains the <span>SpriteBuilder</span> project and source code for the specific progress of one chapter. Whenever you get stuck you can look up the solution in that repository.</p>
<h2 id="getting-involved">Getting Involved</h2>
<p>I would love to have your feedback and hear about issues you found in this book. You can report issues on this GitHub repository: <a href="https://github.com/SpriteBuilder-Book/Errata" class="uri">https://github.com/SpriteBuilder-Book/Errata</a>. And you can email me at any time with feedback or questions: me@benjamin-encz.de.</p>
<h1 id="introduction-to-spritebuilder-and-cocos2d">Introduction to <span>SpriteBuilder</span> and <span>Cocos2D</span> </h1>
<p>Now it’s time to dive into 2D Game Development! I don’t assume any previous knowledge, we will be discussing all the relevant concepts throughout this chapter.</p>
<p>Besides general 2D programming concepts, this chapter will introduce <span>SpriteBuilder</span> and <span>Cocos2D</span> - the Open Source tools that we will use throughout this book. <span>Cocos2D</span> is the game engine (or framework) and <span>SpriteBuilder</span> is a visual content editor for <span>Cocos2D</span>.</p>
<h2 id="installing-the-software">Installing the Software</h2>
<p>First things first. Let’s install the software used throughout this book. If you haven’t developed for iOS or Mac OS X before, you first need to download <span>Xcode</span>. The software is available on the <em>App Store</em>. You should find it when searching for the term <em><span>Xcode</span></em>:</p>
<div class="figure">
<img src="images/Chapter2/install_xcode.png" alt="Xcode on the Mac App Store" />
<p class="caption"><span>Xcode</span> on the Mac App Store</p>
</div>
<p>Next, you should install <span>SpriteBuilder</span>. <span>SpriteBuilder</span> comes bundled with the latest version of <span>Cocos2D</span>, so we don’t need to install these two tools separately.</p>
<p><span>SpriteBuilder</span> is also available on the <em>App Store</em>. You can find it by searching for <em>SpriteBuilder</em>. Note that you should always use the latest version of Mac OS X and <span>Xcode</span> together with <span>SpriteBuilder</span> (as of this writing MacOS X 10.10 and <span>Xcode</span> 6.3).</p>
<div class="figure">
<img src="images/cocos2d/setup/mac_appstore_install.png" alt="SpriteBuilder on the Mac App Store" />
<p class="caption"><span>SpriteBuilder</span> on the Mac App Store</p>
</div>
<p>After a couple of minutes the <span>SpriteBuilder</span> installation should be completed. Later throughout this chapter you will learn how to set up your first project.</p>
<h2 id="introduction-to-cocos2d">Introduction to <span>Cocos2D</span></h2>
<p>First, let us take a look at the features of <span>Cocos2D</span>. That will give you a basic understanding of which tasks you will hand off to the framework. Later on we will be discussing all of these features in detail:</p>
<dl>
<dt>Scene Graphs</dt>
<dd><p><span>Cocos2D</span> provides the concepts of scenes and nodes. Everything that is rendered to the screen is part of a hierarchical <em>scene graph</em>. Instead of performing custom drawing code you define what your scene looks like by providing a scene graph and <span>Cocos2D</span> will render it for you.</p>
</dd>
<dt>Rendering Engine</dt>
<dd><p>When using <span>Cocos2D</span> you don’t need to write your own rendering code. <span>Cocos2D</span> provides a rendering engine built on top of OpenGL ES.</p>
</dd>
<dt>Action System</dt>
<dd><p>A sophisticated action system allows you to define movements of objects and animations instead of writing a lot of custom code.</p>
</dd>
<dt>Physics Engine</dt>
<dd><p>The <span>Cocos2D</span> physics engine automatically calculates movements of objects, collisions and more.</p>
</dd>
<dt>Node Library</dt>
<dd><p><span>Cocos2D</span> provides a large set of nodes as part of the framework. Nodes can be used to represent images, UI elements, solid colors, etc.</p>
</dd>
</dl>
<p>There are many more features - but this brief outline shows the most important. This should help you see why almost all game developers these days use game engines instead of building all of these features from scratch.</p>
<p>Let’s take a closer look at how <span>Cocos2D</span> works.</p>
<h3 id="the-cocos2d-technology-stack">The <span>Cocos2D</span> Technology Stack</h3>
<p><span>Cocos2D</span> is built on top of OpenGL ES 2.0 (and it has recently added experimental support for Apple’s <em>Metal</em> Framework). If you have ever written OpenGL code before, you know that it takes a lot of code to render even the most primitive scenes. OpenGL is a fairly low level framework that gives the graphics programmer a lot of control over how and when certain tasks are performed - more control then you need for most 2D games. <span>Cocos2D</span> abstracts all of these tasks for you.</p>
<p>While <span>Cocos2D</span> makes it easy to mix in custom OpenGL code, many <span>Cocos2D</span> developers write entire games without writing any OpenGL code at all.</p>
<p>The following diagram shows which technologies are used by <span>Cocos2D</span>:</p>
<div class="figure">
<img src="images/cocos2d/TechnologyStack.png" alt="Cocos2D Technology Stack" />
<p class="caption"><span>Cocos2D</span> Technology Stack</p>
</div>
<p>The goal of a game engine like <span>Cocos2D</span> is that the game developer doesn’t have to get in touch with rendering at all. Instead a developer defines which scenes exist in a game, which nodes are part of these scenes and which size, position and appearance these nodes have and <span>Cocos2D</span> will use OpenGL to render these scenes for him.</p>
<p>In order to provide this functionality <span>Cocos2D</span> consists of variety of classes - some important ones will be discussed in this chapter. All <span>Cocos2D</span> classes use the <em>CC</em> prefix (<span>CCScene</span>, <span>CCNode</span>, etc.).</p>
<p>When working with a 2D game engine for the first time, you will be introduced to a whole set of new terminology. We have already talked about nodes and scenes but we haven’t discussed what these terms mean. We will now start discussing the most important ones.</p>
<h3 id="scenes">Scenes</h3>
<p>Scenes are the basic building blocks of all <span>Cocos2D</span> games, they are the highest level on which game content can be structured. Each scene in <span>Cocos2D</span> is a full-screen canvas. For every full-screen section of your game you will use <em>one</em> scene.</p>
<p>Here’s an illustration from the <span>Cocos2D</span> documentation:</p>
<div class="figure">
<img src="images/Chapter1/scenegraph.png" alt="A game with 3 scenes" />
<p class="caption">A game with 3 scenes</p>
</div>
<p>You can see that the game consists of the start scene, the gameplay scene and the game over scene.</p>
<p>Scenes are represented by the <span>CCScene</span> class. Another important <span>Cocos2D</span> class for scene handling is <span>CCDirector</span>. As shown in the image above, the <span>CCDirector</span> class is responsible for deciding which scene is currently active in the game (<span>Cocos2D</span> only allows one active scene at a time). Whenever a developer wants to display a scene or transition between two scenes she needs to use the <span>CCDirector</span> class.</p>
<p>This means creating and displaying a new scene is a two step process:</p>
<ol>
<li><p>Create a new instance of <span>CCScene</span></p></li>
<li><p>Tell the <span>CCDirector</span> to display this new scene</p></li>
</ol>
<p>You will learn a lot more about this down the road, but the important bottom line is: <em>Scenes are the highest level of structure in your game and a class called <span>CCDirector</span> decides which scene is currently displayed</em>.</p>
<h3 id="nodes">Nodes</h3>
<p>Everything that is visible in your <span>Cocos2D</span> game (and a couple of invisible objects) are <em>nodes</em>. Nodes are used to structure the content of a scene. Every node can have other nodes as its children. <span>Cocos2D</span> provides a huge amount of different node types. Every node type is a subclass of <span>CCNode</span>.</p>
<p>Most nodes are used to represent an object on the screen (an image, a solid color, an UI element, etc.), a few other nodes are only used as containers that group other nodes. All nodes have a size, position and children (and many other properties which are less important for us right now). Here are some of the popular node types of <span>Cocos2D</span>:</p>
<dl>
<dt>CCSprite</dt>
<dd><p>represents an image or an animated image. Used for characters, enemies, etc.</p>
</dd>
<dt>CCColorNode</dt>
<dd><p>a node that displays one plain color.</p>
</dd>
<dt>CCLabelTTF</dt>
<dd><p>a node that can represent text in any TTF font.</p>
</dd>
<dt>CCButton</dt>
<dd><p>an interactive node that can receive touches.</p>
</dd>
</dl>
<p>Nodes and their children form a scene graph. The concept of a scene graph isn’t unique to <span>Cocos2D</span>; it is a common concept of 2D and 3D graphics. A scene graph is a hierarchy of many different nodes.</p>
<h3 id="scene-graphs">Scene Graphs</h3>
<p>Let’s take a look at simple example of a <span>Cocos2D</span> scene:</p>
<div class="figure">
<img src="images/cocos2d/SceneGraph.png" alt="Cocos2D Scene Graph" />
<p class="caption"><span>Cocos2D</span> Scene Graph</p>
</div>
<p>The image above shows <span>Cocos2D</span>’s rendering output for a scene alongside with its scene graph. The root node of the scene graph is a <span>CCScene</span>. The first child is a <span>CCNode</span> with two children of type <span>CCLabelTTF</span>. This <span>CCNode</span> is the first example of a grouping node: it groups the score caption label and the label displaying the actual score.</p>
<p>Instances of <span>CCNode</span> don’t have any appearance they are solely used to group other nodes. Throughout this book you will learn that it often makes sense to group nodes under certain parent nodes. The main reason is that all children are placed <em>relative</em> to their parents. So if we would want to move the scoreboard of the example above to the top right corner, we would only have to move the parent node instead of both child nodes. As you can imagine this becomes even more relevant in games that have ten or more entries in their scoreboard.</p>
<p>[Structuring Nodes] Always group nodes that logically belong together under one parent node. That will save you a lot of time when you change the layout of your scene.</p>
<p>The other two objects in the scene graph are simpler. Both are CCSprites, one represents the background image the other one the main character.</p>
<p>For some games scene graphs can get very complex and include hundreds of different nodes. The key takeaways for now are:</p>
<ol>
<li><p>Every node in <span>Cocos2D</span> can have children</p></li>
<li><p>A hierarchy of nodes is called a scene graph</p></li>
<li><p>Children of nodes are placed relative to their parents - often it is useful to group nodes that are moved together under one parent</p></li>
<li><p><span>Cocos2D</span> renders the screen output based on a scene graph that you provide</p></li>
</ol>
<p>As you can see nodes are the most important building block of <span>Cocos2D</span> games - they are used to build everything that is visible in your game. Because it is so important to understand how nodes work in <span>Cocos2D</span>, we will take a look at the most important properties and methods that <span>CCNode</span> provides.</p>
<h3 id="Introduction_CCNode">An Introduction to CCNode</h3>
<p>Every visible object in your game will be a subclass of <span>CCNode</span>. Because you use nodes to build and arrange your scenes, it is important to understand how nodes are positioned and how positions of nodes can be accessed. Let’s take a look at the most relevant properties and methods to access and change size and position of a <span>CCNode</span>:</p>
<dl>
<dt>contentSizeInPoints</dt>
<dd><p>the size of this node in points</p>
</dd>
<dt>positionInPoints</dt>
<dd><p>the position of this node in points, expressed relative to the parent of this node</p>
</dd>
<dt>anchor point</dt>
<dd><p>the anchor point is the center point for rotations and the reference point for positioning this node</p>
</dd>
<dt>boundingBox</dt>
<dd><p>the bounding box is a rectangle that encloses a node. You can only read it but not set it</p>
</dd>
</dl>
<p>The <em>contentSizeInPoints</em> and <em>positionInPoints</em> properties express the size and the position of a <span>CCNode</span>. If you have worked with UI frameworks before, you should be familiar with similar properties.</p>
<p>The <em>bounding box</em> and the <em>anchor point</em> however, are concepts that are more specific to game development. The bounding box is a rectangle that encloses the entire node. You will see an example of a bounding box in the next diagram. The anchor point is relevant for positioning and rotating nodes.</p>
<p>Let’s take a look at how anchor points influence positioning first. We know that the position of a node is expressed relative to its parent. More specifically, every node position in <span>Cocos2D</span> is expressed from the <em>position reference corner</em> of the parent to the anchor point of the <span>CCNode</span>. Here’s a visual example in which a bear node is placed relative to a background node:</p>
<div class="figure">
<img src="images/cocos2d/ccnode/NodePositioning.png" alt="CCNode positioning example" />
<p class="caption"><span>CCNode</span> positioning example</p>
</div>
<p>As you can see, the <em>anchor point</em> and the <em>position reference corner</em> influence the position of a node. The anchor point can have any value between (0, 0), representing the bottom left corner of a node and (1,1), representing the top right corner of a node. In the example above the bear has an anchor point of (0.5, 0.5) which is at the center of the bear. By choosing an anchor point of (0.5, 0.5), the <em>center</em> of the bear will be positioned at (215, 285). If we would choose an anchor point of (0,0) the <em>bottom left</em> corner of the bear would be positioned at (215, 285).</p>
<p>The <em>position reference corner</em> lets us define from which of the four corners of the parent node we are expressing the position of a node. In the example above the top left corner is the <em>position reference corner</em>. We will discuss how to use position reference corners when we start creating games that shall work on multiple screen sizes.</p>
<p>The anchor point is not only important for the positioning of a node. It has a second important function - it represents the center of rotation for a <span>CCNode</span>. Every <span>CCNode</span> rotates around its own anchor point. Here’s an example of rotating the bear node with two different anchor points:</p>
<div class="figure">
<img src="images/cocos2d/ccnode/Rotation.png" alt="CCNode positioning example" />
<p class="caption"><span>CCNode</span> positioning example</p>
</div>
<p>There is a lot more to learn about <span>CCNode</span>. For now our only goal is to get a basic understanding of how <span>Cocos2D</span> games are structured and what the most important parts of <span>Cocos2D</span> are.</p>
<p>You now know that <span>Cocos2D</span> game are structured into scenes. You know that everything visible in your game is a <span>CCNode</span> and that every <span>CCNode</span> can have multiple children. You also got a basic understanding of how nodes are positioned in <span>Cocos2D</span>.</p>
<p>Now that you have that basic understanding, we will take a look at a second tool which we will be using throughout this book: <span>SpriteBuilder</span>.</p>
<h2 id="introduction-to-spritebuilder">Introduction to <span>SpriteBuilder</span></h2>
<p>So far you have learned the basics of the game engine that we will use. Now we will take a look at a tool called <span>SpriteBuilder</span> which we will use to create the majority of our game content. The main purpose of <span>SpriteBuilder</span> is to provide a visual editor for the creation of scenes, animations and more. For most games you will create some basic mechanics in code (enemy movement, score mechanism, etc.) but you will create most of your game content in <span>SpriteBuilder</span> since it is a lot easier to create levels, menus and other scenes in an editor that provides you with a live preview instead of putting these scenes together in code.</p>
<p>If you have never used <span>SpriteBuilder</span> before, it is very important to understand that everything that can be implemented in <span>SpriteBuilder</span> can also be implemented in code. <span>SpriteBuilder</span> is not part of the game engine, it simply allows you to configure <span>Cocos2D</span> scenes and nodes in an editor instead of configuring them in code.</p>
<h3 id="creating-a-first-project">Creating a First Project</h3>
<p>To dive into the features of <span>SpriteBuilder</span> we will create our first project!</p>
<ol>
<li><p>Create a new project by opening SpriteBuilder and selecting <em>File &gt; New &gt; Project...</em>:</p>
<p><img src="images/cocos2d/setup/spritebuilder_new_project.png" alt="image" /></p></li>
<li><p><span>SpriteBuilder</span> will ask for a name and a location for the new project. Name it <em>HelloSB</em>. Also make sure to choose <em>Swift</em> as the primary project language:</p>
<p><img src="images/Chapter1/new_project_swift.png" alt="image" /></p></li>
</ol>
<p>After you create the project the folder structure should look similar to this:</p>
<div class="figure">
<img src="images/cocos2d/setup/project_structure.png" alt="SpriteBuilder project folder structure" />
<p class="caption"><span>SpriteBuilder</span> project folder structure</p>
</div>
<p>Every <span>SpriteBuilder</span> project is contained in a <em>.spritebuilder</em> folder. This folder stores all <span>SpriteBuilder</span> project files - along with an <span>Xcode</span> project.</p>
<p>[<span>SpriteBuilder</span> and Xcode] <span>SpriteBuilder</span> will create an <span>Xcode</span> project for every new project you create! The <span>Xcode</span> project will automatically contain the newest version of <span>Cocos2D</span> - very handy.</p>
<p>Later on you will learn more about how the <span>SpriteBuilder</span> project and the <span>Xcode</span> project work together. The general rule is that all code will be part of the <span>Xcode</span> project and most content creation will happen in the <span>SpriteBuilder</span> project.</p>
<h3 id="the-editor">The Editor</h3>
<p>When you have created your first <span>SpriteBuilder</span> project, you will see that the <span>SpriteBuilder</span> UI gets enabled. Let’s take a look at the different parts of the editor to get a better understanding of <span>SpriteBuilder</span>.</p>
<p>The <span>SpriteBuilder</span> interface is divided into 4 main sections:</p>
<p><img src="images/spritebuilder/spritebuilder_ui.png" alt="image" /></p>
<ol>
<li><p><em>Resource/Component Browser:</em> Here you can see the different resources and scenes you have created or added to your project. You can also select different types of Nodes and drag them into your scene.</p></li>
<li><p><em>Stage:</em> The stage will preview your current scene. Here you can arrange all of the nodes that belong to a scene.</p></li>
<li><p><em>Timeline:</em> The timeline is used to create animations within SpriteBuilder. It also displays the scene graph of the current scene.</p></li>
<li><p><em>Inspector:</em> Once you select a node in your scene, this detail view will display a lot of editable information about that node. You can modify positions, content (the text of a label, for example) and physics properties.</p></li>
</ol>
<p>Let’s take a closer look at some of the most important views.</p>
<h4 id="file-view">File View</h4>
<p>The first tab in the resource/component browser represents the <em>File View</em>. It lists all the <em>.ccb</em> files and resources that are part of the <span>SpriteBuilder</span> project:</p>
<p><img src="images/spritebuilder/spritebuilder_fileview.png" alt="image" /></p>
<p>In this view you can add new resources and restructure your project’s folder hierarchy.</p>
<h4 id="node-library">Node Library</h4>
<p>The third tab in the left view is the <span>Node Library</span>:</p>
<p><img src="images/spritebuilder/spritebuilder_nodeview.png" alt="image" /></p>
<p>This panel shows you all available node types you can use to construct your Gameplay scenes and menus. You will drag these nodes from this view to the stage in the center to add them to your scenes.</p>
<h4 id="inspector">Inspector</h4>
<p>The first tab of the Detail View (the right panel) is the Inspector. Once you have selected an object on your stage you can use this panel to modify many of its properties, like position and color:</p>
<p><img src="images/spritebuilder/spritebuilder_inspector.png" alt="image" /></p>
<h4 id="code-connections">Code Connections</h4>
<p>The second tab on the right panel let’s you manage code connections for your selected node. As mentioned previously the entire code for your games will be written as part of the <span>Xcode</span> project. This view allows you to create connections between the <span>Xcode</span> project and the <span>SpriteBuilder</span> project. For example you can set a custom Swift class for a node or you can select a method in your code that shall be called once a button in your scene is tapped. We will discuss the use of code connections extensively throughout this book.</p>
<p><img src="images/spritebuilder/spritebuilder_codeconnections.png" alt="image" /></p>
<h3 id="ccb-files"><span>CCB File</span>s</h3>
<p><span>CCB File</span>s are the basic building blocks of your <span>SpriteBuilder</span> project. Every scene in your game that is created with <span>SpriteBuilder</span> is represented by one <span>CCB File</span>. However <span>CCB File</span>s are not only used to create entire scenes - they are used to create any kind of scene graph. <span>SpriteBuilder</span> provides different kinds of document types depending on which type of scene graph you want to create. You get an overview of the available <span>CCB File</span> types when you create a new one, by selecting <em>New &gt; File...</em> from the <em>File</em> menu in <span>SpriteBuilder</span>: [DocumentTypes]</p>
<p><img src="images/spritebuilder/new-ccb.png" alt="image" /></p>
<p>These are the different document types briefly explained:</p>
<dl>
<dt>Scenes</dt>
<dd><p>will fill the full screen size of the device.</p>
</dd>
<dt>Nodes</dt>
<dd><p>used primarily for grouping functionality.</p>
</dd>
<dt>Layers</dt>
<dd><p>are nodes with a content size. This is useful, for instance, when creating levels or contents for scroll views.</p>
</dd>
<dt>Sprites</dt>
<dd><p>used to create (animated) characters, enemies, etc.</p>
</dd>
<dt>Particles</dt>
<dd><p>is used to design particle effects.</p>
</dd>
</dl>
<p>You will get a good understanding when to use which type of <span>CCB File</span> once we get started with our example projects. The key takeaway is that <span>CCB File</span>s are used by <span>SpriteBuilder</span> to store an entire scene graph including size, positions and many other properties of all the nodes that you have added.</p>
<h3 id="Publish">How <span>SpriteBuilder</span> and <span>Xcode</span> Work Together</h3>
<p>I have mentioned how <span>SpriteBuilder</span> and <span>Xcode</span> integrate a couple of times briefly. In order to be a well versed and efficient <span>SpriteBuilder</span> game developer it is very important to understand the details of this cooperation.</p>
<p>When creating a <span>SpriteBuilder</span> project, <span>SpriteBuilder</span> will create and maintain a corresponding <span>Xcode</span> project. In <span>SpriteBuilder</span> you’ll create multiple <span>CCB File</span>s that describe the content of the scenes in your game. You will also add the resources that you want to use in your game and set up code connections to interact with the code in your <span>Xcode</span> project. <span>Xcode</span> will be the place where you add code to your project and from where you run the actual game.</p>
<p>Since <span>Xcode</span> is the tool that actually compiles and runs your game it needs to know about all the scenes and resources that are part of your <span>SpriteBuilder</span> project. Therefore <span>SpriteBuilder</span> has a <strong>publish</strong> functionality, provided by a button in the top left corner of the interface:</p>
<div class="figure">
<img src="images/spritebuilder/spritebuilder_publish_button.png" alt="Use the publish button to update your Xcode project with the latest changes in your SpriteBuilder project." />
<p class="caption">Use the publish button to update your <span>Xcode</span> project with the latest changes in your <span>SpriteBuilder</span> project.</p>
</div>
<p>Using that button, you publish your changes in your <span>SpriteBuilder</span> project to your <span>Xcode</span> project. Whenever you changed your <span>SpriteBuilder</span> project and want to run it you should hit this button before building the <span>Xcode</span> project. Alternatively you can use the shortkey <em>CMD + Shift + O</em>.</p>
<p>Here’s a diagram that visualizes how <span>SpriteBuilder</span> and <span>Xcode</span> work together:</p>
<div class="figure">
<img src="images/spritebuilder/spritebuilder_publishing.png" alt="SpriteBuilder creates and organizes a Xcode project for you. Adding all the resources and scenes you have created." />
<p class="caption"><span>SpriteBuilder</span> creates and organizes a <span>Xcode</span> project for you. Adding all the resources and scenes you have created.</p>
</div>
<p><span>CCB File</span>s created in <span>SpriteBuilder</span> store a scene graph; the hierarchy and positions of your nodes. When publishing a <span>SpriteBuilder</span> project the <span>CCB File</span>s and all other project resources are copied to your <span>Xcode</span> project. [CCBReader] When running the project in <span>Xcode</span> a class called CCBReader will parse your <span>CCB File</span>s and create the according <span>CCNode</span> subclasses to reconstruct the scene graph you have designed in <span>SpriteBuilder</span>.</p>
<p>If you would use <span>Cocos2D</span> without <span>SpriteBuilder</span> you would manually create instances of <span>CCNode</span>, <span>CCSprite</span>, etc. in code and add children to these nodes - essentially building the entire scene graph in code.</p>
<p>When using <span>SpriteBuilder</span> the CCBReader class will build this scene graph for you, based on the information stored in the <span>CCB File</span>s that you created in <span>SpriteBuilder</span>.</p>
<p>Another important part of information contained in <span>CCB File</span>s that we have not discussed in detail yet are <em>Code Connections</em>.</p>
<h3 id="CodeConnections">Code Connections</h3>
<p>Code connections are used to create links between your scenes in <span>SpriteBuilder</span> and your code in <span>Xcode</span>. There are three basic types of code connections:</p>
<dl>
<dt>Custom Classes</dt>
<dd><p>are an important information for the CCBReader. As mentioned previously the CCBReader builds the scene graph by creating different nodes based on the information in your <span>CCB File</span>. By default it will create an instance of <span>CCSprite</span> for every sprite you added in <span>SpriteBuilder</span> an instance of <span>CCNode</span> for every node you added, etc. Often however you will want to add custom behaviour to a node (for example a movement pattern for an enemy). Then you will have to use the <em>Custom Class</em> property to tell the CCBReader which class it should instantiate instead of the default one. Whichever class you enter here needs to be a subclass of the default class (e.g. a subclass of <span>CCSprite</span>). You will learn how to use this feature in the final project of this chapter!</p>
</dd>
<dt>Variable Assignments</dt>
<dd><p>If you have assigned a <em>Custom Class</em> you can use variables assignments to retrieve references to different nodes in the scene. For example a character might want a reference to its right arm node (a child of the character node) in order to move it.</p>
</dd>
<dt>Callbacks</dt>
<dd><p>are only available to UI elements like buttons and sliders. They allow you to decide which method should be called on which class once a user interaction occurs.</p>
</dd>
</dl>
<p>Now you should have an idea about what code connections are used for and which kinds exist. We will discuss the details of all types when we use them as part of our example projects.</p>
<h2 id="a-first-spritebuilder-project">A first <span>SpriteBuilder</span> project</h2>
<p>You have already created the <span>SpriteBuilder</span> project called <em>HelloSB</em>. Now we will start adding some content to it. The project built in this chapter will consist of two scenes one start screen and one game screen. In the game screen the user will be able to spawn randomly colored squares that rotate, by tapping on the screen.</p>
<div class="figure">
<img src="images/firstproject/first_project.png" alt="The project build throughout this chapter" />
<p class="caption">The project build throughout this chapter</p>
</div>
<p>By creating this project you will learn all of the following:</p>
<ul>
<li><p>Creating scenes in <span>SpriteBuilder</span></p></li>
<li><p>Creating code connections (callbacks, variable assignments and custom classes)</p></li>
<li><p>Switching between different scenes</p></li>
<li><p>Manipulating a scene graph from code (add/remove nodes, load CCB Files and add them to the scene)</p></li>
<li><p>Using the <span>Cocos2D</span> action system to create animations</p></li>
<li><p>Using the <span>Cocos2D</span> touch handling system to capture touches</p></li>
</ul>
<h3 id="setting-up-the-first-scene">Setting Up the First Scene</h3>
<p>Now it is time to open the <em>HelloSB</em> <span>SpriteBuilder</span> project. We want to add a <em>Start Button</em> to the first scene. When this button is tapped we want to switch to the second scene.</p>
<h4 id="positioning-the-first-button">Positioning the first button</h4>
<p>Start by adding a button to the first scene by following the three steps outlined below:</p>
<div class="figure">
<img src="images/firstproject/add_button.png" alt="The project build throughout this chapter" />
<p class="caption">The project build throughout this chapter</p>
</div>
<dl>
<dt>(1)</dt>
<dd><p>Open <em>MainScene.ccb</em> by double clicking it in the left resource pane. Then open the third tab in the left pane, the <em>Node Library</em>. Remember, this section shows you all the different node types supported by <span>SpriteBuilder</span>. Select the <em>Button</em> and drag it over to the stage, dropping it below the existing label. Dropping it on the stage will add this node to your scene. Another way of adding a node to a scene is dropping it to the timeline at the bottom of the screen - we will look at this later.</p>
</dd>
<dt>(2)</dt>
<dd><p>Make sure the button is selected, because we want to change some properties of it. Whenever you have selected a node the right pane will display all the properties you can edit. Navigate to the <em>Title</em> textfield in the property pane and change the title of the button to <em>Start Game</em>.</p>
</dd>
<dt>(3)</dt>
<dd><p>So far - so simple. Step number three will expose you to a very interesting feature of <span>SpriteBuilder</span>: the positioning system. It will allow you to not only use absolute positions but also positions that are relative to the size of the parent node. We want to center the button horizontally so we choose the position type for the X component to be <em>in percent of parent container</em> by selecting that option from the dropdown menu. Now we assign <em>50</em> as value, because that expresses the horizontal center of the parent container. Whichever screen this button will be displayed on, it will always be vertically centered (yes, even on an iPad)!</p>
</dd>
</dl>
<p>[Positioning System in <span>Cocos2D</span> and <span>SpriteBuilder</span>] [PositioningSystem] The positioning system in <span>Cocos2D</span> is designed from the ground up to make it easy to design scenes and user interfaces for different screen sizes and resolutions. The comfortable days where the 3.5-inch iPhone was the only available iOS device and defining layouts with absolute positions was acceptable are finally over. Today app and game developers face a variety of different devices and customers justifiably expect your software to work great on all of them. <span>Cocos2D</span> offers the following properties on <span>CCNode</span>s to allow developers to design their interfaces with great flexibility:</p>
<ul>
<li><p>Anchor Point</p></li>
<li><p>Reference Corner</p></li>
<li><p>Position Type</p></li>
<li><p>Size Type</p></li>
</ul>
<p>We will use the positioning system throughout multiple chapters in this book. If you want to learn more about dynamic layouts right away, you should read our tutorial: <a href="https://www.makeschool.com/tutorials/dynamic-layouts-with-spritebuilder-and-cocos2d-3-x/" class="uri">https://www.makeschool.com/tutorials/dynamic-layouts-with-spritebuilder-and-cocos2d-3-x/</a>.</p>
<p>Now the button is placed correctly. Next, we want to assign an action to it. When the button is tapped we want to transition to our second scene.</p>
<h4 id="setting-up-a-code-connection">Setting up a code connection</h4>
<p>Earlier you learned that <span>SpriteBuilder</span> has three types of code connections ([CodeConnections]). Now we will use one of them in our project - <em>Callbacks</em>. Callbacks are only available to nodes that allow for some sort of user interaction (this means they need to be subclasses of <span>CCControl</span>). Buttons, as well as Sliders and Text Fields are some of these types of nodes.</p>
<p>Select the button we have added to the scene earlier and select the second tab of the right pane:</p>
<div class="figure">
<img src="images/firstproject/button_callback.png" alt="Nodes that allow user interaction can use callback methods to connect to the code base of a game" />
<p class="caption">Nodes that allow user interaction can use callback methods to connect to the code base of a game</p>
</div>
<p>Inside the CCControll section you can see two options called <em>selector</em> and <em>target</em>. Here you can choose which method (selector) shall be called on which object (target) when this button is tapped by a user. As selector enter <span>startGame</span>. As target choose <em>Document Root</em>.</p>
<p>[Targets and Selectors] [target<sub>s</sub>elector] The concept of targets and selectors is part of design pattern widely used throughout the Cocoa framework (Target/Action pattern). A <em>selector</em> is a method name and a <em>target</em> is the object that shall receive this method. Further reading: <a href="https://developer.apple.com/library/ios/documentation/general/conceptual/Devpedia-CocoaApp/TargetAction.html" class="uri">https://developer.apple.com/library/ios/documentation/general/conceptual/Devpedia-CocoaApp/TargetAction.html</a></p>
<p>As you can see you cannot choose an arbitrary object to be the target of this callback, you can only choose between two different ones:</p>
<dl>
<dt>Document Root</dt>
<dd><p>The document root is the highest node within the current <span>CCB File</span>. The hierarchy of the <span>CCB File</span> is shown in the <span>SpriteBuilder</span> timeline:</p>
<p><img src="images/firstproject/documentroot_node.png" alt="image" /></p>
<p>If you select the document root as target, the <span>startGame</span> method will be called on the top level <span>CCNode</span>.</p>
</dd>
<dt>Owner</dt>
<dd><p>if you want the callback to call an object that is not part of your <span>CCB File</span> you can use the <em>owner</em> option. Later in this book you will learn how to set up an owner object for a <span>CCB File</span>.</p>
</dd>
</dl>
<p>For our button we have decided that the <span>startGame</span> method should be called on the document root when the button is tapped. Next, we will have to implement this <span>startGame</span> method within our document root. But to which <em>class</em> could we add this method? In order to find that out we need to understand the concept of <em>Custom Classes</em> .</p>
<p>Think about it - by default our document root is an instance of a plain <span>CCNode</span> class. Now we want to call a method called <span>startGame</span> on this object. Our problem: the <span>CCNode</span> class does not have a <span>startGame</span> method! This is where custom classes come to rescue us, they allow us to tell <span>SpriteBuilder</span> that our document root node should <strong>not</strong> be a plain <span>CCNode</span> but should be an instance of a class that we have created and implements our <span>startGame</span> method. To define a custom class for the document root you need to select the document root (the top-level <span>CCNode</span>) from the timeline and open the third tab in the right pane:</p>
<p><img src="images/firstproject/custom_class.png" alt="image" /></p>
<p>In the <em>Custom class</em> textfield a developer can enter a class name. The class entered here needs to be part of the <span>Xcode</span> project related to this <span>SpriteBuilder</span> project. As you can see every new <span>SpriteBuilder</span> project already comes with a custom class set up for the root node of <em>MainScene.ccb</em>. When the CCBReader loads this <span>CCB File</span> it will create an instance of <span>MainScene</span> instead of an instance of <span>CCNode</span>. Now our document root object is a <span>MainScene</span> object! That also means that we have saved the puzzle of where to add the code for the <span>startGame</span> method - it needs to be part of the <span>MainScene</span> class. The <span>MainScene</span> class is already part of the template <span>Xcode</span> project generated by <span>SpriteBuilder</span>.</p>
<p>Now that we have the connection set up, it is time to add some code.</p>
<p>[Requirements for Custom Classes] Every custom class has to be a subclass of the default class for a given node. For example, the default class for the <em>Sprite</em> node in <span>SpriteBuilder</span> is <span>CCSprite</span>. If a developer wants to set a custom class for a Sprite node, that class has to be a subclass of <span>CCSprite</span>. <strong>Why?</strong> <span>SpriteBuilder</span> expects custom classes to only <strong>add</strong> behaviour to a default class. All the functionality of the default class should remain available. If your custom class for a Sprite node doesn’t allow <span>SpriteBuilder</span> to set an image, because it is a subclass of <span>CCNode</span> the CCBReader and finally also you will run into problems!</p>
<h4 id="adding-code-to-a-spritebuilder-project">Adding Code to a <span>SpriteBuilder</span> project</h4>
<p>When creating games with <span>SpriteBuilder</span> we are always working with two tools. <span>SpriteBuilder</span> to create interfaces and scenes (our game content) and <span>Xcode</span> to add code (game mechanics, etc.). Now we will add our first few lines of code to the <span>MainScene</span> class.</p>
<p>It’s time to publish the changes in our <span>SpriteBuilder</span> project, so that they are available in our <span>Xcode</span> project.</p>
<ol>
<li><p>Use the publish button in the top left corner of the <span>SpriteBuilder</span> interface ([Publish]). Or use the shortkey: <em>Option + CMD + S</em>.</p></li>
<li><p>Open the <span>Xcode</span> project (it’s called <em>HelloSB.xcodeproj</em> and is located inside the <em>HelloSB.spritebuilder</em> folder). You can also use a shortcut provided by <span>SpriteBuilder</span>: CMD + Shift + O</p></li>
</ol>
<p>You will see that project contains two classes, <span>AppDelegate</span> and <span>MainScene</span>. As part of the template for new <span>SpriteBuilder</span> projects the <span>MainScene</span> class has already been created for you. For any subsequent custom classes you link in your <span>SpriteBuilder</span> project you will need to create the according classes in <span>Xcode</span> on your own.</p>
<p>Now it’s finally time to implement the <span>startGame</span> method.</p>
<p>Open the <em>MainScene.swift</em> and file and add the following method:</p>
<pre><code>  func startGame() {
    println(&quot;Start Game&quot;)
  }</code></pre>
<p>For now we will simply use the <span>println</span> function to log a text to the console once the button is pressed, this is an easy way to check if our code connection is set up correctly.</p>
<p>[Displaying the console in <span>Xcode</span>] To display the console in <span>Xcode</span> select <em>View -&gt; Debug Area -&gt; Activate Console</em>.</p>
<p>Now, run the <span>Xcode</span> project by hitting the play button in the top left corner. You should check that you have selected <em>HelloSB</em> as target and are set up to run the app on a simulator (indicated by a device description, e.g. iPhone Retina, instead of a device name):</p>
<p><img src="images/firstproject/run_app.png" alt="image" /></p>
<p>Hitting the run button will compile your app and launch it on an iOS simulator. Once your app is launched, click on the start button and check the console for the log message. You should see something similar to this:</p>
<p><img src="images/firstproject/button_success_log.png" alt="image" /></p>
<p>You have successfully set up your first <span>SpriteBuilder</span> scene and have created a working code connection! Later on this button shall trigger a transition to the Gameplay scene. Before we can implement that we need to create the second scene in our <span>SpriteBuilder</span> project!</p>
<p>[Common errors with code connections] If you are not getting the expected result, check for all of these common errors:</p>
<ul>
<li><p>Have you published your <span>SpriteBuilder</span> project before running in <span>Xcode</span>?</p></li>
<li><p>Is the custom class of the root node of <em>MainScene.ccb</em> set to <span>MainScene</span></p></li>
<li><p>Does the button in <em>MainScene.ccb</em> have the correct target and selector?</p></li>
<li><p>Make sure to read the console log as it usually includes details about the failed code connection</p></li>
</ul>
<h3 id="creating-the-gameplay-scene">Creating the Gameplay Scene</h3>
<p>Now it’s time to create your first scene using <span>SpriteBuilder</span> from scratch. The scene we are going to create is the Gameplay scene.</p>
<p>Open <span>SpriteBuilder</span> to create a new scene. To create a new scene (or any other <span>CCB File</span>) select: <em>File -&gt; New -&gt; File…</em> from the <span>SpriteBuilder</span> menu. Then you will see the following dialog appear:</p>
<p><img src="images/firstproject/new_scene.png" alt="image" /></p>
<p>The dialog will ask you for a name for the <span>CCB File</span> and a template type. For now we are going to use the name <em>Gameplay.ccb</em> and the type <em>Scene</em>. Once you hit the create button you will see the new, blank scene appear.</p>
<p>Our Gameplay scene will remain empty. As you have seen in the outline of the project, we want to dynamically add colored objects to the game whenever the user taps into our Gameplay scene - initially however, the scene will be blank. Now that we have created the Gameplay scene we can add the transition from the Main scene to the Gameplay scene.</p>
<h3 id="adding-a-scene-transition">Adding a Scene Transition</h3>
<p>Transitions are essential for any game. We use them whenever we want to switch from one scene to another. Transitions cannot be configured in <span>SpriteBuilder</span>, they always need to be implemented in code.</p>
<p><span>Cocos2D</span> has one central class that is responsible for displaying the active scene and generating transitions between different scenes: <span>CCDirector</span>. CCDirector is implemented as a singleton - thus there’s only one CCDirector per <span>Cocos2D</span> game. The instance can be accessed through the class method <span>CCDirector.sharedInstance()</span>.</p>
<p>[CCDirector is versatile!] CCDirector is responsible for a lot more than only handling active scenes and scene transitions. It is basically a collection of different global <span>Cocos2D</span> settings. The scene handling methods however are the most frequently used CCDirector methods.</p>
<p>CCDirector provides a large collection of methods to present scenes with and without transitions, here are the most important ones:</p>
<pre><code>- (void)presentScene:(CCScene *)scene;
- (void)presentScene:(CCScene *)scene withTransition:(CCTransition *)transition;
- (void)pushScene:(CCScene*) scene;
- (void)pushScene:(CCScene *)scene withTransition:(CCTransition *)transition;
- (void)popScene;
- (void)popSceneWithTransition:(CCTransition *)transition;
- (void)popToRootScene;
- (void)popToRootSceneWithTransition:(CCTransition *)transition;</code></pre>
<p>[<span>Cocos2D</span> is written in Objetive-C] Yes I know, this isn’t Swift code! <span>Cocos2D</span> is written entirely in Objective-C. While it plays nicely with our Swift only code, you will be forced to read some Objective-C headers once in a while. Luckily these header files aren’t too cryptic!</p>
<p><span>Cocos2D</span> has two different approaches for displaying a new scene. <strong>Replacing</strong> the current scene with a new one, using the <span>presentScene:</span> methods, or <strong>Pushing</strong> the new scene on top of the currently active one using the <span>pushScene:</span> methods. Whichever type you choose, you always have the option to provide a transition effect for presenting a scene with an animation, or not to provide a transition effect and display the new scene instantaneously. If you want to provide an effect you need to create an instance of <span>CCTransition</span>.</p>
<p>Before we look into using transition effects, let’s take a look at the differences between pushing and replacing a scene.</p>
<h4 id="replacing-scenes-vs.-pushing-scenes">Replacing scenes vs. pushing scenes</h4>
<p>When you simply want to replace the current scene with a new one you should use the <span>presentScene:</span> method. Here’s an example:</p>
<pre><code>CCDirector.sharedDirector().presentScene(myNewScene)</code></pre>
<p>Very simple! So why would one use the <span>pushScene:</span> method? Let’s assume the following scenario where we want to implement a menu with multiple submenus. Whenever a player hits the back button, he wants to return to the previous menu:</p>
<p><img src="images/firstproject/navigation_stack.png" alt="image" /></p>
<p>This is a case where it is a lot easier to use <span>pushScene:</span> and <span>popScene:</span> instead of simply replacing the currently running scene. Whenever a player selects a button that opens a sub-menu, we call:</p>
<pre><code>CCDirector.sharedDirector().pushScene(submenu)</code></pre>
<p>And whenever a player hits the <em>back</em> button in one of the sub-menus, we simply call:</p>
<pre><code>CCDirector.sharedDirector().popScene()</code></pre>
<p>This works, because CCDirector will remember the scene that we pushed before the current one and can easily return to it. This concept is called a <em>Navigation Stack</em>.</p>
<p>If you would try to implement the menu hierarchy using <span>presentScene:</span> you would have to explicitly define which scene each back button will present. The code for the back button of <em>SubMenu</em> would look like this:</p>
<pre><code>CCDirector.sharedDirector().presentScene(mainMenu)</code></pre>
<p>If you would ever change the menu hierarchy in your game, you would have to change the code for each back button.</p>
<p>[Scene transitions - the right way] For <strong>one time transitions</strong> for example from a splash screen to the gameplay of a game, use <span>presentScene</span>. Whenever a user can navigate between your scenes, e.g. by using a back button to return to the previous scene, make use of the navigation stack by using the <span>pushScene</span> and <span>popScene</span> methods.</p>
<h4 id="adding-transition-effects">Adding transition effects</h4>
<p>For every scene replacement method there’s one variation that takes an instance of <span>CCTransition</span>. The CCTransition instance provides an animation for transitions between different scenes. CCTransition provides multiple convenience initializers which makes for short and readable code. Here’s an example of how to create an animated transition:</p>
<pre><code>let transition = CCTransition(fadeWithDuration: 1.0)
CCDirector.sharedDirector().presentScene(gameplayScene, withTransition: transition)</code></pre>
<p>First we create a transition object, then we hand it to the <span>presentScene</span> method.</p>
<h4 id="implementing-a-scene-transition-for-our-game">Implementing a scene transition for our game</h4>
<p>Now that you know the most important details about scene transitions, let’s add the transition from our start scene to our Gameplay scene. Earlier we have already implemented a test version of the <span>startGame</span> method, where we printed a log message to the console. Now we are going to implement a transition.</p>
<ol>
<li><p>Open <em>MainScene.m</em> in <span>Xcode</span>.</p></li>
<li><p>Replace the current implementation of <span>startGame</span> with this one:</p>
<pre><code>func startGame() {
  let gameplayScene = CCBReader.loadAsScene(&quot;Gameplay&quot;)
  let transition = CCTransition(fadeWithDuration: 1.0)
  CCDirector.sharedDirector().presentScene(gameplayScene, withTransition: transition)
}</code></pre></li>
</ol>
<p>Now that you are familiar with scene transitions, the only interesting line should be the one where we use the <span>CCBReader</span> to load a <span>CCB File</span>. The CCBReader class was briefly introduced at the beginning of this chapter ([CCBReader]). It is capable of reading <span>SpriteBuilder</span>s <em>.ccbi</em> files and creating the according <span>Cocos2D</span> classes from the information stored in them. Whenever we want to load a scene or any other type of node that we created in <span>SpriteBuilder</span> into code we use the CCBReader class. In the lines shown above we load the content of our <em>Gameplay.ccb</em> into a variable called <span>gameplayScene</span>. The <span>loadAsScene:</span> method wraps whatever scene graph you load into an instance of <span>CCScene</span>. Use it whenever you want to load a <span>CCB File</span> in order to present is as a full-screen scene.</p>
<p>Then we create a simple fade transition and store that object in the <span>transition</span> variable. Finally we use the <span>CCDirector</span> to present our loaded scene with the transition we just created.</p>
<p>You are now ready to run this version of the game from <span>Xcode</span>! When you tap the <em>Start</em> button on the first scene, you should see a transition to our black Gameplay scene that lasts for one second.</p>
<p><strong>Well done!</strong> You have learned how to create a new scene in <span>SpriteBuilder</span> and how to implement transitions between different scenes in a game. Now let’s implement the actual gameplay of our first example game!</p>
<p>[.ccb and .ccbi] The files with the file extension <em>.ccb</em> are in XML-format and are used by <span>SpriteBuilder</span> to store and read information about a scene or node created in <span>SpriteBuilder</span>. When a <span>SpriteBuilder</span> project gets published, <span>SpriteBuilder</span> generates a binary version of each <em>.ccb</em> file. The file extension for these binary files is <em>.ccbi</em> and they are a lot smaller than their corresponding <em>.ccb</em> files. The CCBReader reads these smaller binary files at runtime and turns them into nodes.</p>
<h3 id="implementing-the-gameplay">Implementing the Gameplay</h3>
<p>Now it’s time to implement the actual gameplay. For our first project we want to keep that fairly simple. Whenever a user touches the screen, we want to add a rotating square with a random color to the gameplay scene. We position the square at the location of the touch.</p>
<h4 id="creating-the-square-ccb-file">Creating the Square <span>CCB File</span></h4>
<p>Let’s start by creating the square we want to spawn during the game in <span>SpriteBuilder</span>. In most games each of your different entities will be represented by an individual <span>CCB File</span>. That makes it easy to load entities in Code and reuse them throughout different scenes. For that reason we will create an individual <span>CCB File</span> for our rotating squares.</p>
<p>Create a new <span>CCB File</span> of type <em>Node</em>:</p>
<p><img src="images/firstproject/square_ccb.png" alt="image" /></p>
<p>The squares we generate in the game shall have a color. A default <span>CCNode</span> cannot display a color - it doesn’t have a <span>backgroundColor</span> property. In order to display a color we need to use a <span>CCNodeColor</span>. The <span>SpriteBuilder</span> node for a CCNodeColor is called <em>Color Node</em>. The root node of every <span>CCB File</span> is a plain <span>CCNode</span>, that cannot be changed. This means we need to add the <em>Color Node</em> as a child of the root node of <em>Square.ccb</em>.</p>
<p>Add a <em>Color Node</em> by performing the following steps:</p>
<p><img src="images/firstproject/square_add_colornode.png" alt="image" /></p>
<dl>
<dt>(1)</dt>
<dd><p>Open the <em>Node Library</em> and drag a <em>Color Node</em> to the stage or to the timeline in order to add it to the root node of of <em>Square.ccb</em>.</p>
</dd>
<dt>(2)</dt>
<dd><p>Center the new <em>Color Node</em> on the root node by selecting an <em>Anchor Point</em> of (0.5, 0.5). Change the <em>Content Size</em> of the node to (50, 50).</p>
</dd>
</dl>
<p>Now the basic square is set up. Next, we need to set up a code connection. Earlier you have seen the use of <em>Custom Classes</em> and <em>Callbacks</em>, now we will use the third type of code connections supported by <span>SpriteBuilder</span> a <em>Variable Assignment</em>. Variable assignments are generally used when we want to access a part of our scene graph in code. In our game, whenever a new square is created we want to set a random color for this square. Generating a random color is something we need to do in code and cannot do in <span>SpriteBuilder</span>. This also means that we need a way to <em>apply</em> the random color we generate in code to our square that we have set up in <span>SpriteBuilder</span>. The displayed color is defined in the <em>Color Node</em> that we just added. We will need a reference to this <em>Color Node</em> to change the color of our square from code. Let’s add a code connection to make this possible.</p>
<p><strong>Select CCNodeColor from the timeline</strong> (and make sure that you have selected the Color Node and not the Root Node!) and open the connection tab (the second tab on the right pane):</p>
<p><img src="images/Chapter1/square_code_connection.png" alt="image" /></p>
<p>As the variable name (entered in the text field), choose <em>colorNode</em>. As the second option you need to choose the object to which this variable will be assigned to. Just as for callbacks you can choose between the <em>Document Root</em> and the <em>Owner</em> ([DocumentRoot<sub>O</sub>wner]). We choose the <em>Document Root</em>, which means that <span>SpriteBuilder</span> will attempt to store a reference to the <em>Color Node</em> in a property called <em>colorNode</em> on the root node object of this <span>CCB File</span>.</p>
<p>We now face the same ’problem’ as earlier when we set up a <em>Callback</em>. The root node of <em>Square.ccb</em> is a plain <span>CCNode</span> and a plain <span>CCNode</span> does not have a property called <em>colorNode</em>! We once again need to define a custom class for the root node of this <span>CCB File</span>.</p>
<p><span>Variable Assignments, Callbacks and Custom Classes</span> Always remember that you practically cannot set up a <em>Variable assignment</em> or a <em>Callback</em> for the <em>Document Root</em> without also setting a custom class for the root node of the corresponding <span>CCB File</span>. You will always want to access properties or methods that aren’t available on the default type of the root node.</p>
<p><strong>Select the root CCNode node</strong> from the timeline and set the custom class for this node to <em>Square</em>:</p>
<p><img src="images/firstproject/square_custom_class.png" alt="image" /></p>
<p>When the <em>CCBReader</em> reads this <span>CCB File</span> it will create an instance of the class <em>Square</em> as the root node and it will assign a reference to the <em>Color Node</em> to a property of <em>Square</em> called <em>colorNode</em>. This way we will be able to access the <em>Color Node</em> and change the color of our square programmatically!</p>
<h4 id="setting-up-a-custom-class-for-the-gameplay">Setting up a custom class for the Gameplay</h4>
<p>In our <em>Gameplay</em> scene we want to respond to touches and spawn squares. All of that functionality needs to be implemented in code. Therefore we need to define a custom class for the root node of our <em>Gameplay.ccb</em> (if you struggle with the following instructions you can double check how we set up a custom class for <em>Square.ccb</em>).</p>
<ol>
<li><p>Open <em>Gameplay.ccb</em></p></li>
<li><p>Select the root <span>CCNode</span> from the timeline</p></li>
<li><p>Open the code connections tab (the second tab on the right pane)</p></li>
<li><p>Define the <em>Custom Class</em> to be <em>Gameplay</em></p></li>
</ol>
<p>We’ve set up multiple code connections throughout this chapter. In order for all of them to work, we need to publish the <span>SpriteBuilder</span> project.</p>
<ol>
<li><p>Publish the <span>SpriteBuilder</span> project</p></li>
<li><p>Switch to your Xcode project</p></li>
</ol>
<h4 id="creating-the-square-class">Creating the Square class</h4>
<p>Let’s create the classes and properties that we are referencing in the <span>SpriteBuilder</span> project to our Xcode project. We’ll get started with the <span>Square</span> class.</p>
<ol>
<li><p>Open <span>Xcode</span> and create a new Swift class by selecting <em>File -&gt; New File…</em> and choosing <em>Cocoa Touch Class</em>:</p>
<p><img src="images/Chapter1/new_cocoa_touch.png" alt="image" /></p></li>
<li><p>Hit the next button</p></li>
<li><p>Choose <em>Square</em> as the class name and make sure you have selected <strong>Swift</strong> as the programming language! Define the class to be a subclass of <span>CCNode</span>:</p>
<p><img src="images/Chapter1/new_cocoa_touch_2.png" alt="image" /></p></li>
<li><p>Hit the <em>Next</em> button to create the file.</p></li>
</ol>
<p>Remember, a custom class always has to be a subclass of the node type you have selected in <span>SpriteBuilder</span>. The node type of the root node of <em>Square.ccb</em> is a <span>CCNode</span> therefore <span>Square</span> needs to be a subclass of <span>CCNode</span>.</p>
<p>Now open <em>Square.swift</em> and add the property <span>colorNode</span> to the <span>Square</span> class. This property is the one that we defined in <span>SpriteBuilder</span> to store the reference to the <span>CCNodeColor</span> that displays the color of our square:</p>
<pre><code>class Square : CCNode {
  
  weak var colorNode : CCNodeColor!
  
}</code></pre>
<p>Note that we are using a <span>weak</span> variable of forcefully unwrapped type (indicated by the trailing <em>!</em> after the type name). This will be default for all code connections throughout this book for the following two reasons:</p>
<ol>
<li><p>The property is declared as <span>weak</span> because it doesn’t <em>own</em> the referenced child node. We only want to use this property as a reference - we know that another part of our game is responsible for keeping the referenced object around. In this case the <span>colorNode</span> will stay in memory as long as it is a child node of a scene that is rendered on the screen. Unowned references should always be marked as <span>weak</span> (or by using the Swift keyword <span>unowned</span>, but that is beyond the scope of this book!).</p></li>
<li><p>Since the code connection we set up will not have a value assigned as soon as <span>Square</span> is initialized we need to declare the property as either <em>optional</em> or <em>forcefully unwrapped</em>. Swift has pretty strict initialization rules! We choose <em>forcefully unwrapped</em> because we know that <span>Cocos2D</span> guarantees that this property will have a value as soon as the <span>CCB File</span> is loaded and <span>didLoadFromCCB</span> is called (we will discuss the <span>Cocos2D</span> lifecycle in detail shortly). Given this knowledge it’s preferable to choose <em>forcefully unwrapped</em> over <em>optional</em> because it avoids a lot of optional-unwrapping code.</p></li>
</ol>
<p>[Swift initialization and optionals] You can read more about Swift initialization and optionals in our following tutorial: <a href="https://www.makeschool.com/tutorials/learn-swift-by-example-part-3-classes-and-initialization" class="uri">https://www.makeschool.com/tutorials/learn-swift-by-example-part-3-classes-and-initialization</a></p>
<p>Now that we have a reference to the <span>CCNodeColor</span> we need a position in code where we can set a random color for that node.</p>
<p>The requirements for this project state that we need to choose a random color for our Square as soon as it is added to the Gameplay scene. <strong>How can we be informed about the square being added to the Gameplay scene?</strong> Therefore we need to take a closer look at what we call the <strong>Node Lifecycle</strong>.</p>
<p>We have five important methods that inform us about certain lifecycle events on <span>CCNode</span> subclasses. All of the methods below are called on all nodes that are part of the scene that is being loaded/presented/hidden:</p>
<dl>
<dt>didLoadFromCCB</dt>
<dd><p>this method is called when the <span>CCBReader</span> has created the complete node graph from a CCB file and all code connections are set up. You implement this method to access and manipulate the content of a node. You cannot access child nodes of the node or code connection variables before this method is called. Note that this method is only called on nodes that are loaded from <span>CCB File</span>s.</p>
</dd>
<dt>onEnter/onEnterTransitionDidFinish</dt>
<dd><p>are called as soon as a node enters the stage. If you are presenting a scene with an animated transition, <span>onEnter</span> will be called on that scene as soon as the transition starts and <span>onEnterTransitionDidFinish</span> will be called when the transition completes. If a scene or node is being presented/added without an animated transition both methods are called directly after each other. It’s also important to note that the content size of a node that is expressed relative to the parent node will not be available until <span>onEnter</span> has been called.</p>
</dd>
<dt>onExitTransitionDidStart/onExit</dt>
<dd><p>are called as soon as a node leaves the stage. If you are hiding a scene with an animated transition, <span>onExitTransitionDidStart</span> will be called on that scene as soon as the transition starts and <span>onExit</span> will be called when the transition completes. If a scene or node is being hidden/removed without an animated transition both methods are called directly after each other.</p>
</dd>
</dl>
<p>You will get to see lots of examples of how to use the lifecycle methods throughout this book, for now we know that we need to override <span>onEnter</span> to pick and apply a random color for our square as soon as it gets added to the Gameplay scene. It is also important to know that you need to call the <span>super</span> implementation if you override any of the <span>onEnter…</span> or <span>onExit…</span> methods. <span>CCNode</span> has its own implementation of these methods and they are important for the functionality of the framework - if you do not call them this will result in unexpected behaviour throughout your game.</p>
<p>[Overriding <span>Cocos2D</span> lifecycle methods] As of <span>Cocos2D</span> 3.1 not calling <span>super</span> when overriding one of these lifecycle methods will result in a compiler warning - this can save a lot of debugging time. You are interested in how that can be done? <span>Cocos2D</span> makes use of a nice compiler feature to implement this requirement. You simply need to add an according <span>__attribute__</span> to the method definition:</p>
<pre><code> -(void) onEnter __attribute__((objc_requires_super));</code></pre>
<p>Add this implementation of <span>onEnter</span> to <em>Square.m</em>:</p>
<pre><code>override func onEnter() {
  super.onEnter()
  
  let red = Float(arc4random_uniform(256)) / 255.0
  let green = Float(arc4random_uniform(256)) / 255.0
  let blue = Float(arc4random_uniform(256)) / 255.0
  
  colorNode.color = CCColor(red: red, green: green, blue: blue)
}</code></pre>
<p>The lines above generate three random numbers, with a value between 0.0 and 1.0, using the C function <span>arc4random_uniform</span>. That’s one number for each color component. These three numbers are used to create an instance of <span>CCColor</span> and set it as the color of our node. Since <span>CCColor</span> wants to be initialized with <span>Float</span> values we need to explicitly create <span>Float</span> numbers from the result of calling the <span>arc4random_uniform</span> function which returns a <span>UInt32</span>.</p>
<p>Now the square will appear in a random color as soon as we add it to a scene. The second requirement for our square is that it shall rotate while on the screen. One of the ways to move and/or animate a node in <span>Cocos2D</span> is using the <span>Cocos2D</span> Action System.</p>
<h3 id="adding-actions-in-code">Adding Actions in Code</h3>
<p>Throughout most of the book we will be using <span>SpriteBuilder</span> to create animations. It is still very useful to know how to generate actions in code, as that approach can be easier to use for certain types of animations.</p>
<p>The <span>Cocos2D</span> Action System provides a simple and expressive way for developers to implement animated changes and movements such as: <em>Move the main character to the top left corner of the screen over the period of 2 seconds</em>.</p>
<p>The Action System consists of dozens of subclasses of <span><span>CCAction</span></span> - a majority of these actions represent some type of animated movement or transformation. <span>CCActionMoveTo</span> for example moves a node to a target position within a provided time interval. This is how to use it:</p>
<pre><code>let move = CCActionMoveTo(duration:2.0, position:ccp(20, 100))
aSimpleNode.runAction(move)</code></pre>
<p>All actions can be run by calling the <span>runAction</span> method of <span>CCNode</span> and providing the action as an argument.</p>
<p>The Action System also provides several actions that take other actions as arguments. One example is <span>CCActionReverse</span> that reverses the action it is initialized with - for example moving a node backwards instead of forwards. Another example is <span>CCActionRepeatForever</span> that takes another action and - exactly, repeats it forever!</p>
<p>Let’s use the Action System to rotate our squares!</p>
<p>Add the following lines to the <span>onEnter</span> method of <em>Square.m</em> to make the square rotate endlessly:</p>
<pre><code>let rotate = CCActionRotateBy(duration: 2.0, angle: 360.0)
let repeatRotation = CCActionRepeatForever(action: rotate)

runAction(repeatRotation)</code></pre>
<p>One of the nicest aspects of the Action System is that it produces very readable code, just as the one shown above. We rotate our square by 360 degrees in 2 seconds and repeat that forever!</p>
<p>Now our implementation of <span>Square</span> is complete. Along the way you have learned about code connections, generating random numbers and using the action system. Let’s move on to implementing the <span>Gameplay</span> class so that we can see our delightfully colored and rotating squares in action.</p>
<h4 id="creating-the-gameplay-class">Creating the Gameplay class</h4>
<p>After we have set up all the code for the square it’s now time to implement the gameplay. In <span>SpriteBuilder</span> we have already created the <span>CCB File</span> <em>Gameplay.ccb</em> and set up the custom class for the root node to be <span>Gameplay</span>. Now we need to add the <span>Gameplay</span> class in <span>Xcode</span> and implement touch handling code that creates a square and adds it to the gameplay scene as soon as a player touches the screen.</p>
<p>Create the new class just as you have created the <span>Square</span> class.</p>
<ol>
<li><p>In <span>Xcode</span> select <em>File -&gt; New -&gt; File…</em> and select <em>Cocoa Touch Class</em>.</p></li>
<li><p>This class needs to be a subclass of <span>CCNode</span> since the root node of <em>Gameplay.ccb</em> is a <span>CCNode</span>.</p></li>
<li><p>Name the class <span>Gameplay</span></p></li>
</ol>
<h4 id="Introduction_FirstTouchHandling">Adding Touch Handling to the Gameplay</h4>
<p>Now we need to add touch handling to the Gameplay scene. This will be the first time you will add User Interaction to a <span>Cocos2D</span> game!</p>
<p>The <span>Cocos2D</span> touch handling system works on a <em>per node basis</em>. This means that every <span>CCNode</span> instance can choose to receive touches or not. You can activate touch handling on any node using the <span>userInteractionEnabled</span> property. If <span>userInteractionEnabled</span> is set to <span>true</span>, <span>Cocos2D</span> will automatically check if your node is touched by the user. In <span>Cocos2D</span> the front most node receives touch events first.</p>
<p>Each touch in <span>Cocos2D</span> has a lifecycle. That lifecycle consists of four different states and four corresponding methods that are called on your <span>CCNode</span>:</p>
<dl>
<dt>touchBegan</dt>
<dd><p>called when a touch begins</p>
</dd>
<dt>touchMoved</dt>
<dd><p>called when the touch position of a touch changes</p>
</dd>
<dt>touchEnded</dt>
<dd><p>called when a touch ends because the user stops touching the screen</p>
</dd>
<dt>touchCancelled</dt>
<dd><p>called when a touch is cancelled because user moves touch outside of the touch area of a node</p>
</dd>
</dl>
<p>You can override all of these methods in any <span>CCNode</span> subclass in order to respond to these lifecycle events. For our simple example now, we only need to respond to the <span>touchBegan</span> method.</p>
<p>Note, that you always need to implement <span>touchBegan</span> in order to receive touches! If <span>touchBegan</span> is not implemented in your class, any touches will be ignored and none of the other lifecycle events will be called.</p>
<p>[The <span>Cocos2D</span> Touch System] We will see more complicated use cases of the <span>Cocos2D</span> touch system throughout other examples in this book. If you are interested in more details right away you should read:<a href="https://www.makeschool.com/docs/#!/cocos2d/1.2/user-interaction" class="uri">https://www.makeschool.com/docs/#!/cocos2d/1.2/user-interaction</a> and <a href="https://www.makeschool.com/tutorials/touch-handling-in-cocos2d" class="uri">https://www.makeschool.com/tutorials/touch-handling-in-cocos2d</a>.</p>
<p>Now that you know the basics, let’s implement touch handling for the <span>Gameplay</span> class. First, we need to enable user interaction. A great place to do this is in the <span>onEnterTransitionDidFinish</span> method. Why? If you have an animated transition that presents your gameplay scene you will likely not want to the player to interact with your game before this transition has finished entirely.</p>
<p>Let’s start receiving touches in the <span>Gameplay</span> class!</p>
<p>Add the following method to <em>Gameplay.swift</em>:</p>
<pre><code>override func onEnterTransitionDidFinish() {
  super.onEnterTransitionDidFinish()
  
  self.userInteractionEnabled = true
}</code></pre>
<p>As discussed earlier you need to call the <span>super</span> implementation of the lifecycle method you are overriding. In the second step we are setting <span>userInteractionEnabled</span> to <span>true</span>. Now <span>Cocos2D</span> knows that this node wants to receive touch events.</p>
<p>In the next step we need to decide which touch events we want to subscribe to and implement the corresponding methods. For this simple game we only need to know when a touch begins because we will add a square to the screen immediately. This means we only need to implement the <span>touchBegan</span> method.</p>
<p>Add the following implementation to <span>Gameplay.swift</span>:</p>
<pre><code>override func touchBegan(touch: CCTouch!, withEvent event: CCTouchEvent!) {
  let touchPosition = touch.locationInNode(self)
  let square = CCBReader.load(&quot;Square&quot;)
  addChild(square)
  square.position = touchPosition
}</code></pre>
<p>The <span>touchBegan</span> method above will be called every time the user taps onto the gameplay scene. As one parameter of this method we receive a <span>CCTouch</span>. The <span>CCTouch</span> stores all information about the touch. <span>Cocos2D</span> provides a useful method called <span>locationInNode:</span>. This method returns the touch position relative to the provided node. In the first line we call this method to receive the touch location within the gameplay scene (referred to by <span>self</span>). In the next line we load one <span>Square</span> node using the <span>CCBReader</span>. Then we add that loaded square as a child to the gameplay scene. The <span>addChild:</span> method of <span>CCNode</span> will add the square to the node hierarchy of the gameplay scene. As soon as node becomes part of the node hierarchy of the currently active scene it will be displayed on the screen. Finally we choose a position for the square. We provide the touch position that we determined in the first line - this way the square will be spawned exactly at the position touched by the player.</p>
<p>Now it’s time to run your project again. Once the game started, select the <em>Start</em> button to go to the gameplay scene then click onto the screen multiple times to simulate touches. Every time you simulate a touch you should see a new square spawn at the touch position:</p>
<p><img src="images/firstproject/spinning_squares.png" alt="image" /></p>
<h2 id="summary">Summary</h2>
<p><strong>Well done!</strong> You have come a very long way from the blank project to a first simple game that uses scene transitions, actions and the <span>Cocos2D</span> touch system.</p>
<p>This chapter has introduced you to the fundamental concepts of 2D game programming, <span>SpriteBuilder</span> and <span>Cocos2D</span>. But this is only the very beginning. In the next chapter we will start working on a much more complex game that will teach you many more important concepts of mobile game development with <span>SpriteBuilder</span> and <span>Cocos2D</span>.</p>
<h1 id="asset-handling-and-basic-game-mechanics">Asset Handling and Basic Game Mechanics</h1>
<p>Graphics and Sounds are the essence of every good game. In the first chapter you have learned the very basics of <span>SpriteBuilder</span> and <span>Cocos2D</span> by building a game that only uses plain colored shapes. In this chapter you will learn how <span>SpriteBuilder</span> helps you to integrate assets into your game. Learning by example is the most fun, so starting in this chapter and lasting until the end of the book, we will build a full iOS game! The final product is available on the App Store! Here’s what the final game will look like:</p>
<div class="figure">
<img src="images/Chapter2/final_game.png" alt="The game that is built throughout this book" />
<p class="caption">The game that is built throughout this book</p>
</div>
<p>The goal of that game is for the user to drag a pot across the screen in order to collect food items and avoid inedible kitchen equipment and other electronic devices.</p>
<p>When building this type of game you can choose whether or not to use the <span>Cocos2D</span> physics engine. For this book I have chosen to build the game <strong>without</strong> it. Here are the reasons:</p>
<ol>
<li><p>Games built with a physics engine have a very different feel from games where all objects are moved through custom code. A physics engine is never 100% accurate. The player can feel this in collisions and other interactions throughout the game. This is one of the main reasons while many platformers do not rely on physics engines. They are great for game concepts that entirely rely on a physics engine - such as the popular game angry birds. But there are more games out there that don’t use a physics engine than the other way round.</p></li>
<li><p>Many games are a little bit easier to build with a physics engine, but you will end up learning a very different set of skills. The main goal of this book is to teach you skills that you can use to build your own games. I felt I can provide more value by implementing object movement, collision detection, etc. customly.</p></li>
<li><p>There are already great resources on physics based games with <span>SpriteBuilder</span> and <span>Cocos2D</span> out there, including our Peeved Penguins tutorial (<a href="https://www.makeschool.com/tutorials/getting-started-with-spritebuilder/" class="uri">https://www.makeschool.com/tutorials/getting-started-with-spritebuilder/</a>) and Steffen Itterheim’s book <em>Learn SpriteBuilder</em> (<a href="http://www.apress.com/9781484202630" class="uri">http://www.apress.com/9781484202630</a>).</p></li>
</ol>
<p>Now you should have a decent idea of the game we will be building throughout the rest of this book! Let’s get started with the first part: asset management and setting up the basic mechanics of our game.</p>
<h2 id="adding-assets-to-a-spritebuilder-project">Adding Assets to a SpriteBuilder Project</h2>
<p>First of all we need to create a new <span>SpriteBuilder</span> project. You will also need to download the art pack for this game.</p>
<ol>
<li><p>Create a new <span>SpriteBuilder</span> project and name it <em>FallingObjects</em>.</p></li>
<li><p>Download the assets from <a href="http://bit.ly/sb-book-assets" class="uri">http://bit.ly/sb-book-assets</a>.</p></li>
<li><p>Unzip the folder once the download completes</p></li>
<li><p>Add the assets to the project by dragging the entire folder into the left <em>File View</em> in the left panel of <span>SpriteBuilder</span>:</p>
<p><img src="images/Chapter2/DragAssets.png" alt="image" /></p></li>
</ol>
<p>Great, now we have some assets to use in our game. Now is a good time to take a close look at how <span>SpriteBuilder</span> and <span>Cocos2D</span> handle assets.</p>
<h2 id="asset-handling-in-spritebuilder-and-cocos2d">Asset Handling in <span>SpriteBuilder</span> and <span>Cocos2D</span></h2>
<p>One of the main goals of <span>SpriteBuilder</span> is to make game development for multiple device types as easy as possible. This means that games should automatically be able to run on differently sized iPhones and on iPads. Since each of these devices has a different resolution <span>Cocos2D</span> and <span>SpriteBuilder</span> allow developers to use different assets to target them. <span>SpriteBuilder</span> provides four different resolution categories:</p>
<dl>
<dt>phone</dt>
<dd><p>resolution for non-retina iPhone</p>
</dd>
<dt>phone-hd</dt>
<dd><p>retina resolution for iPhone</p>
</dd>
<dt>tablet</dt>
<dd><p>resolution for non-retina iPad</p>
</dd>
<dt>tablet-hd</dt>
<dd><p>resolution for retina iPad</p>
</dd>
</dl>
<p>Luckily using <span>SpriteBuilder</span> there is no need to provide four resolutions for each asset thanks to <strong>automatic downscaling</strong>. Per default <span>SpriteBuilder</span> assumes that all assets added to a project are provided in <em>tablet-hd</em> resolution, then <span>SpriteBuilder</span> generates downscaled images for the other resolutions. While you can provide different images for the four targets, <span>SpriteBuilder</span> only knows three resolution types:</p>
<dl>
<dt>1x</dt>
<dd><p>non-retina images</p>
</dd>
<dt>2x</dt>
<dd><p>retina images</p>
</dd>
<dt>4x</dt>
<dd><p>double sized retina images</p>
</dd>
</dl>
<p>By default <span>SpriteBuilder</span> maps these resolution types to the different devices in a way that every asset has the same relative size, in relation to the screen size, on every device. This means games running on an iPad will look very similar to games running on an iPhone, except that they have a slightly different aspect ratio. Here is an example from on of our tutorials showing what a game looks like on different device types:</p>
<div class="figure">
<img src="images/Chapter2/ResultsFlexibleScaleMode.png" alt="From our tutorial Dynamic Layouts with SpriteBuilder and Cocos2D" />
<p class="caption">From our tutorial <em>Dynamic Layouts with SpriteBuilder and Cocos2D</em></p>
</div>
<p>Let’s take a look at all of the options for image sizes in the context of our <span>SpriteBuilder</span> project - that will make it easier to understand how the parts fit together.</p>
<p>Let’s start in the project settings. When you open the project settings (<em>File -&gt; Project Settings…</em>) you can see the available downscaling options:</p>
<p><img src="images/Chapter2/DownScalingGlobal.png" alt="image" /></p>
<p>The <em>Default scaling from</em> setting defines the <em>global</em> downscaling option, i.e. which resolution <span>SpriteBuilder</span> uses to generate all of our assets. Individual assets can define their own behaviour, thereby overriding this global setting. To make support of multiple devices as easy as possible you should provide all of your assets in <em>4x</em> resolution and keep this default setting.</p>
<p>When you select an individual asset from the File View you can see different downscaling settings:</p>
<p><img src="images/Chapter2/DownScalingPerAsset.png" alt="image" /></p>
<p>Each asset can have its own <em>Scale from</em> setting. <em>Default</em> means that the global project setting applies (in this project: downscaling from <em>4x</em>). Additionally you can see how the different resolution types are mapped to the different device types. Here you could for example choose that a certain asset should not be scaled up on retina tablets by choosing a <em>2x</em> resolution for <em>tablethd</em> - however, the default settings work best most of the time.</p>
<p>For future reference, this is an example that shows you which sizes your assets will have on the different devices by default:</p>
<table>
<tbody>
<tr class="odd">
<td align="left"><strong>Device</strong></td>
<td align="left"><strong>Default Resolution Type</strong></td>
<td align="left"><strong>Size on Screen (points)</strong></td>
<td align="left"><strong>Size in Pixels</strong></td>
</tr>
<tr class="even">
<td align="left">iPhone</td>
<td align="left">1x</td>
<td align="left">50x50</td>
<td align="left">50x50</td>
</tr>
<tr class="odd">
<td align="left">iPhone Retina</td>
<td align="left">2x</td>
<td align="left">50x50</td>
<td align="left">100x100</td>
</tr>
<tr class="even">
<td align="left">iPad</td>
<td align="left">2x</td>
<td align="left">100x100</td>
<td align="left">100x100</td>
</tr>
<tr class="odd">
<td align="left">iPad Retina</td>
<td align="left">4x</td>
<td align="left">100x100</td>
<td align="left">200x200</td>
</tr>
</tbody>
</table>
<p>The key takeaway for now is that it’s best to provide assets in <em>4x</em> resolution in order to build games that look good on all device types. All the assets in the art pack that you downloaded earlier are provided in <em>4x</em> resolution.</p>
<p>That’s enough of theory for now - let’s get started on building the <em>Falling Object!</em> game.</p>
<p>[Different images for different devices] You can not only change the scaling option for an asset on different devices, you can even use an entirely different image for a certain resolution. You can do that by dragging an image <strong>that is currently not part of the <span>SpriteBuilder</span> project</strong> from Finder into one of the four boxes below the asset preview:</p>
<p><img src="images/Chapter2/DifferentImageDevice.png" alt="image" /></p>
<p>Note that images you add this way will be displayed in exactly the size you have added them and will not be downscaled.</p>
<p>[Behind the scenes] If you are interested in how <span>SpriteBuilder</span> and <span>Cocos2D</span> organize assets you can take a look at the resource package (<em>/Packages/SpriteBuilder Resources.sbpack</em>) by right-clicking and selecting <em>Show Package Contents</em>:</p>
<p><img src="images/Chapter2/behindscenes_resourcepack.png" alt="image" /></p>
<p>You will see that <span>SpriteBuilder</span> groups images inside the assets folder into a <em>resources-auto</em> folder, all images in that folder are subject to automatic downscaling. If you explicitly add images for a certain resolution as shown with the carrot in the above example, a new folder for that resolution (e.g. <em>resources-phonehd</em>) is created.</p>
<p>In <span>Cocos2D</span> a class called <span>CCFileUtils</span> is responsible for loading the correct images for the current device during runtime. <span>SpriteBuilder</span> uses a special configuration of <span>CCFileUtils</span> that is set up in <span>[CCBReader configureCCFileUtils]</span>.</p>
<h2 id="adding-the-background-image">Adding the Background Image</h2>
<p>Now that we have a basic understanding of how asset management works, lets get started working on our game. For now it will only consist of one scene, so we can start working directly in the <em>MainScene.ccb</em> that is part of the <span>SpriteBuilder</span> template.</p>
<ol>
<li><p>Open <span>MainScene.ccb</span> in your <span>SpriteBuilder</span> project</p></li>
<li><p>Remove all of the content from <span>MainScene.ccb</span> by selecting all nodes on stage and hitting the return key</p></li>
<li><p>Drag the <span>background.png</span> file from the asset folder, in the left panel of <span>SpriteBuilder</span>, to the stage. <span>SpriteBuilder</span> will automatically generate a Sprite Node from this image</p></li>
</ol>
<p>First, remove the existing content so that we can start with a blank scene. Now we can add the background image. To add a sprite to a scene we can simply drag the asset from the left panel to the stage, <span>SpriteBuilder</span> will automatically create an instance of <span>CCSprite</span>. Add the <em>background.png</em> image to the stage.</p>
<p>How should we position this background image? We already have briefly discussed the <span>SpriteBuilder</span> positioning system ([PositioningSystem]). Using the positioning system correctly is especially important when we create games that shall work on both phones and tablets - which we always should try to do. In most cases - like in this game - it is best to center the background image. That way phones and tablets will display a very similar portion of it. The background image that is part of the asset catalog has a size of <em>(2272 x 1536)</em>. This is an image in <em>4x</em> resolution that has exactly the right dimensions to support phones and tablets in landscape mode. It’s high enough for the higher tablet screens and wide enough for the wider phone screens.</p>
<p>Let’s position the background image correctly!</p>
<p>Center the image by choosing a <em>normalized</em> position type (<em>in % of parent container</em>) and setting the position to (50, 50) as shown below:</p>
<p><img src="images/Chapter2/center_background.png" alt="image" /></p>
<p>You can preview what your game will look like on different device types directly in <span>SpriteBuilder</span>, without the need to compile and run the game - you should do this as often as possible! The option is available from the menu <em>Document -&gt; Resolution</em>. You can also use the CMD+1, CMD+2 and CMD+3 shortcuts. This feature will allow you to preview the game on a 3.5-inch iPhone, a 4-inch iPhone and an iPad. [preview<sub>s</sub>creen<sub>s</sub>izes]</p>
<h2 id="create-falling-objects">Create Falling Objects</h2>
<p>Now let’s dive into the implementation of the actual game. The next step should be adding falling objects. Our game will have two categories of objects, ones that should be caught (food) and ones that shouldn’t (electronic devices).</p>
<p>In total we have over ten different objects in our game but these just exist as visual enhancement, actually we are only differing between two types of objects. One way to implement the falling objects would be creating a <span>CCB File</span> for each object but that isn’t actually necessary for this game. We need to create all falling objects dynamically, while the game is running, and for each object we only need to store if it should be caught or not. That can be best accomplished by a subclass of <span>CCSprite</span> that we create in code. This way you will also learn how to use assets you added in <span>SpriteBuilder</span> to create <span>CCSprite</span>s in code.</p>
<p>Open the <span>Xcode</span> project of the game to get started. Remember that you can use the <em>CMD + Shift + O</em> shortcut to do so!</p>
<h3 id="create-a-falling-object-class">Create a Falling Object Class</h3>
<p>In general we have two ways to differentiate objects a player should catch and ones he shouldn’t catch. We could:</p>
<ul>
<li><p>Create two distinct subclasses of <span>CCSprite</span>, each representing one type of object</p></li>
<li><p>Only have one subclass and add a <span>type</span> property to it</p></li>
</ul>
<p>Since our falling objects won’t have any type-specific behaviour, creating two distinct subclasses is not necessary in this case. Instead, as of now, one subclass with a <span>type</span> property is the better solution.</p>
<p>Create a new class called <span>FallingObject</span> and make it a subclass of <span>CCSprite</span>. If you run into issues, check how we created new classes in the last chapter.</p>
<p>The best way to implement our <span>type</span> property is using an enumeration. Enumerations define multiple mutually exclusive values.</p>
<p>Add this enum definition to <em>FallingObject.swift</em>, inside of the <span>class</span> block:</p>
<pre><code>enum FallingObjectType: Int {
  case Good
  case Bad
}</code></pre>
<p>The enumeration above can only be in one of the two states at a time, either <span>.Good</span> or <span>.Bad</span>. Swift supports multiple types of enumerations and enumeration values. In the example above we are creating an enumeration with <em>Raw Values</em>. When we use an enumeration with raw values we need to assign a type as part of the enum definition, as shown in the first line (<span>enum FallingObjectType: Int</span>).</p>
<p>Each enum value will be mapped to one value of this provided type. In the example shown above, the raw value for <span>FallingObjectType.Good</span> will be 0 and the value for <span>FallingObjectType.Bad</span> will be 1. Thanks to auto-increment we do not need to map entries to numbers explicitly. Associating enum values with raw values is optional, throughout this chapter you will see why this feature is useful to us.</p>
<p>[Enumerations in Swift] You can read everything about the different ways of creating enumerations in Swift in the official documentation (<a href="https://developer.apple.com/library/ios/documentation/
Swift/Conceptual/Swift_Programming_Language/Enumerations.html" class="uri">https://developer.apple.com/library/ios/documentation/
Swift/Conceptual/Swift_Programming_Language/Enumerations.html</a>). You can also read a more practical tutorial on Swift enums on our website: (<a href="https://www.makeschool.com/tutorials/learn-swift-by-example-part-2-enums" class="uri">https://www.makeschool.com/tutorials/learn-swift-by-example-part-2-enums</a>)</p>
<p>Additionally we add a property to store the object type. Later we will add an initializer to set the type of the falling object upon initialization.</p>
<p>Add a property to store the falling object type, so that the class looks as following:</p>
<pre><code>import Foundation

class FallingObject: CCSprite {

  enum FallingObjectType: Int {
  case Good
  case Bad
  }
    
  private(set) var type:FallingObjectType
  
}</code></pre>
<p>We define the property to be <em>readonly</em> because we will not support changing the type of a falling object after it has been created. In Swift we can define variables as <em>readonly</em> by marking the <em>setter</em> as private.</p>
<p>Note that the code will not compile at this point. Since <span>type</span> isn’t declared as an optional value, Swift requires us to provide an initializer that sets this value. We will fix this in the next section.</p>
<h3 id="choosing-an-asset-for-a-falling-object">Choosing an Asset for a Falling Object</h3>
<p>We want the game to spawn entirely random falling objects. As you remember we have a couple of assets for both types of objects. Whenever we spawn an object we will need to choose a random asset, based on the object type. A good place to implement this functionality is directly in the <span>FallingObject</span> class. We can provide a custom initializer that allows the class to be initalized with an object type. When this initializer gets called we choose a random asset and apply it as a texture to the <span>FallingObject</span>.</p>
<p>How can we create a list of images for objects that should be caught (e.g. food) and ones that shouldn’t (e.g. radios)? One way of implementing this would be creating two arrays, one for each object type, and storing filenames for different assets in these arrays. As good game developers however, we try to keep game content and code as strictly separated as possible. That makes it easier to update the list of assets later on and it keeps our codebase small and well structured. So instead of creating these arrays in code we could use some sort of resources file that stores information on available images. A very common format for storing such type of information in iOS applications is a <em>plist</em> (Property List). A plist is a special type of XML file that allows us to store structured data. The iOS frameworks have some features that make it easy to interact with plists and to generate them or read them from source code.</p>
<p>Let’s a plist file to our project!</p>
<p>Create a <em>plist</em> by selecting <em>File -&gt; New -&gt; File…</em> from <span>Xcode</span>’s menu. Then select <em>Resource</em> from the left panel and choose <em>Property List</em> on the right:</p>
<p><img src="images/Chapter2/create_plist.png" alt="image" /></p>
<p>As the name choose <em>FallingObjectImages</em>.</p>
<p>Next, let’s fill the <em>plist</em> with two arrays that contain the filenames of the assets that we added in <span>SpriteBuilder</span>, grouped into <em>good</em> and <em>bad</em> objects.</p>
<p>When referencing assets from a <span>SpriteBuilder</span> project you always need to include the folder names in which the images are contained. Instead of referencing the tomato with <span>tomato.png</span> you need to use <span>assets/tomato.png</span> since the image is in the <span>assets</span> folder in the <span>SpriteBuilder</span> project.</p>
<ol>
<li><p>Right-click onto the <em>plist</em> root and select <em>Add Row</em> from the context menu</p></li>
<li><p>Click onto the <em>Type</em> column of the new row and select the type to be <em>Array</em></p></li>
<li><p>Double-click onto to the name of the array and rename it to <em>FallingObjectTypeBadImages</em></p></li>
<li><p>Repeat step 2 and 3 to create another array</p></li>
<li><p>Name that new array <em>FallingObjectTypeGoodImages</em></p></li>
<li><p>Add all the assets as <em>String</em> entries to the according arrays</p></li>
</ol>
<p>The resulting <em>plist</em> should look like this:</p>
<p><img src="images/Chapter2/plist_setup.png" alt="image" /></p>
<p>Now we have a list of all asset names grouped into the two object type categories. Time to implement the <span>FallingObject</span> class.</p>
<p>When a falling object is initialized we want to choose random image from the <em>plist</em> that we just created. The first step is loading the <em>plist</em> in code. Luckily <em>plists</em> consist of Dictionaries, Arrays, Strings, etc. and all of these types exist in Swift as well - there are some very convenient methods to load <em>plists</em> and turn their content into Swift types.</p>
<p>During each playing session we are going to create hundreds of falling objects. Since the images that represent these objects won’t change it would be a waste of resources to load the <em>plist</em> every time we create a new instance of <span>FallingObject</span>. Instead we should only load it once and then keep a reference to it for future use. A good way of doing this is using a class constant to store a reference to the <em>plist</em> once it is loaded.</p>
<p>[Class variables in Swift] Swift 1.2 does not support stored class variables. However, we can use the <span>static</span> keyword to create class-wide variables. The difference between a <span>static</span> and a <span>class</span> variable is that the <span>static</span> variable is not inherited by subclasses. However, that isn’t an issue for our use case!</p>
<p>Let’s add the code that loads the plist and stores the content in a static variable.</p>
<p>Place the following code within the class definition of <span>FallingObject</span> (no worries, we will discuss the code in detail right away):</p>
<pre><code>  private static let imageNames = ImageNames()

  private struct ImageNames {
    var good: [String]
    var bad: [String]
    
    init () {
      let path = NSBundle.mainBundle().pathForResource(&quot;FallingObjectImages&quot;, ofType: &quot;plist&quot;)!
      let imageDictionary:Dictionary = NSDictionary(contentsOfFile: path)! as! [String : AnyObject]
      good = imageDictionary[&quot;FallingObjectTypeGoodImages&quot;] as! [String]
      bad = imageDictionary[&quot;FallingObjectTypeBadImages&quot;] as! [String]
    }
  }</code></pre>
<p>First, we are defining a private static constant. This static constant is initialized with an instance of the structure <span>ImageNames</span> which we declare a few lines later. Since <span>imageNames</span> is a static constant, the expression will ever only be evaluated once. This means only one instance of <span>ImageNames</span> will be created, independently of how often the static constant is accessed.</p>
<p>Inside of the <span>ImageNames</span> struct, the actual work happens. First we declare two array variables that store strings. They store the filenames of the <em>good</em> object assets and the <em>bad</em> object assets. Inside of the initializer we fill these variables.</p>
<p>The initializer takes no parameters. The first line gets the path of the <em>FallingObjectImages.plist</em> file. Then we use a convenience initializer on <span>NSDictionary</span> called <span>contentsOfFile:</span>. That initializer creates a dictionary from a provided plist. This only works because the root element of our plist is a dictionary! Since the file from which we are creating a dictionary might not exist, or could be of an invalid file type, the <span>contentsOfFile:</span> initializer returns an optional. Therefore we need to use the <span>!</span> operator to unwrap the value. Additionally we need to cast the Objective-C dictionary that doesn’t have any type information about the elements it contains to a Swift dictionary of type <span>[String : AnyObject]</span> using the <span>as!</span> operator.</p>
<p>We’ve set up our plist to contain two arrays of strings, <em>FallingObjectTypeGoodImages</em> and <em>FallingObjectTypeBadImages</em> below the root element. We can now extract these two arrays from our dictionary and assign them to the <span>good</span> variable and <span>bad</span> variable, respectively. During this assignment we need to cast the arrays into <span>[String]</span> arrays using the <span>as!</span> operator. This is again necessary because we are receiving an Objective-C Array (<span>NSArray</span>) that cannot store type information about the elements it contains. We however know that this array only contains strings so we want to treat it as a <span>[String]</span> array in Swift.</p>
<p>Now we have successfully set up a static constant that will load the required image names when it is accessed the fist time and store these images on a class level. That will avoid reloading the plist for every instance of <span>FallingObject</span> that we create.</p>
<p>Now that we have access to the image names we can implement the actual initializer of <span>FallingObject</span>. We need to:</p>
<ul>
<li><p>Pick a random image based on the object type</p></li>
<li><p>Call the designated initializer of our superclass <span>CCSprite</span></p></li>
</ul>
<p>Add the following initializer to <span>FallingObject.swift</span>:</p>
<pre><code>  init(type: FallingObjectType) {
    self.type = type
    
    var imageName:String? = nil
    
    if (type == .Good) {
      let randomIndex = randomInteger(FallingObject.imageNames.good.count)
      imageName = FallingObject.imageNames.good[randomIndex]
    } else if (type == .Bad) {
      let randomIndex = randomInteger(FallingObject.imageNames.bad.count)
      imageName = FallingObject.imageNames.bad[randomIndex]
    }
    
    let spriteFrame = CCSpriteFrame(imageNamed:imageName)
    
    super.init(texture: spriteFrame.texture, rect: spriteFrame.rect, rotated: false)
    
    anchorPoint = ccp(0,0)
  }</code></pre>
<p>We start of by storing the type we receive in a property. Then we create a local variable called <span>imageName</span> that we will use to load the correct texture for this object type. Next, we check whether we are initializing a good or a bad object. In each case we generate a random number, using our helper function <span>randomInteger</span>, that picks one image name from the set of available image names in the arrays.</p>
<p>Next, we need to call an initializer of our superclass <span>CCSprite</span>. Here we run into another limitation of the current version of Swift: <strong>we can only call <em>designated</em> initializers of our superclass</strong>, but not any <em>convenience</em> initializers. This means instead of calling:</p>
<pre><code>CCSprite(imageNamed: String!)</code></pre>
<p>We have to call the designated initializer:</p>
<pre><code>CCSprite(texture: CCTexture!, rect: CGRect, rotated: Bool)</code></pre>
<p>This unfortunately means some extra code! We create a <span>CCSpriteFrame</span> with the image name that we have selected from one of our lists, then we use that sprite frame to call <span>CCSprite</span>’s designated initializer. Finally, we set the anchor point of our object to the bottom left corner. That will make it easier to calculate the spawn position later on.</p>
<p>You will notice that this code won’t compile! The <span>randomInteger</span> function is not part of the Swift standard library. Instead it is a convenience function that I’ve created to make generation of random numbers in Swift easier. You need to download the file containing the helper and add it to your project.</p>
<p>Download <span>Helpers.swift</span> from this url <a href="http://bit.ly/sb-book-helpers" class="uri">http://bit.ly/sb-book-helpers</a> and add it to your project.</p>
<p>Now the compiler should be satisfied!</p>
<p>That’s all we need in order to create a <span>FallingObject</span>! Now we can move on and spawn some objects.</p>
<h2 id="spawn-falling-objects">Spawn Falling Objects</h2>
<p>Now it’s time to implement one of the core mechanics of the game: Spawning objects and making them fall from the top of the screen to the bottom. We are going to implement this in <em>MainScene.swift</em>.</p>
<p>We will spawn objects after a certain time period. The spawning objects will start at the top of the screen and fall to the bottom. To not use an increasing amount of memory we will need to take care of removing objects that have fallen below the bottom edge of the screen. A good way to do this is creating an array to store all the objects we spawn.</p>
<p>Add the following property to <span>MainScene</span></p>
<pre><code>class MainScene: CCNode {

  private var fallingObjects = [FallingObject]()

}</code></pre>
<p>We also need to define a falling speed and an interval at which we want to spawn objects. A good way to do this is by defining constants - we want to avoid to have these numbers all over our code.</p>
<p>Add the two constants so that your class definition looks as following:</p>
<pre><code>class MainScene: CCNode {

  private var fallingObjects = [FallingObject]()

  private let fallingSpeed = 100.0
  private let spawnFrequency = 0.5
}</code></pre>
<p>We are going to spawn falling objects ever 0.5 seconds as expressed in the constant <span>spawnFrequency</span>. Through the <span>CCNode</span> class <span>Cocos2D</span> provides convenient methods for scheduling repeating events without the need to instantiate a timer.</p>
<p>Schedule the <span>spawnObject</span> method in the <span>onEnterTransitionDidFinish</span> method:</p>
<pre><code>  override func onEnterTransitionDidFinish() {
    super.onEnterTransitionDidFinish()
    
    // spawn objects with defined frequency
    schedule(&quot;spawnObject&quot;, interval: spawnFrequency)
  }</code></pre>
<p>Remember, <em>onEnterTransitionDidFinish</em> is called as soon as the presentation transition is completed and the current scene is fully visible. This is when we want to kick off the spawning mechanism. All we need to provide is a <em>selector</em>, which simply means a method name as a string, and a frequency at which it shall be called. Now, as soon as the <span>MainScene</span> is presented on the stage, the <span>spawnObject</span> method will be called twice a second. To complete the spawning functionality we will have to implement the <span>spawnObject</span> method and additionally move the spawned objects from the top of the screen to the bottom.</p>
<p>We want to randomly spawn either positive objects that should be caught or negative ones that should not, for that we will generate a random number between 0 and 1. Based on the random number we will generate a falling object of positive or negative type. We will place that spawning object just above the screen at a random X position.</p>
<p>Add the following <span>spawnObject</span> method to <span>MainScene</span>:</p>
<pre><code>  func spawnObject() {
    let randomNumber = randomInteger(2)
    
    let fallingObjectType = FallingObject.FallingObjectType(rawValue:randomNumber)!
    let fallingObject = FallingObject(type:fallingObjectType)
    
    // add all spawning objects to an array
    fallingObjects.append(fallingObject)
    
    // spawn all objects at top of screen and at a random x position within scene bounds
    let xSpawnRange = Int(contentSizeInPoints.width - CGRectGetMaxX(fallingObject.boundingBox()))
    let spawnPosition = ccp(CGFloat(randomInteger(xSpawnRange)), contentSizeInPoints.height)
    fallingObject.position = spawnPosition
    
    addChild(fallingObject)
  }</code></pre>
<p>As you can see here we can create an enum value directly from a number. This is possible because we defined the <span>FallingObjectType</span> enumeration to have a raw integer value earlier. The <span>rawValue</span> initializer is very handy for this specific situation. Besides that the spawning code is not too exciting, it primarily consists of a little math and type conversions. We add each spawned object to the <span>fallingObject</span> array, choose a spawn position and add it as a child to <span>MainScene</span>.</p>
<p>This is a schematic diagram of where we are spawning objects with the code shown above:</p>
<p><img src="images/Chapter2/SpawnObjects.png" alt="image" /></p>
<p>Our current version of the game spawns new objects twice a second at the top of the screen and at a random X position. However, these objects don’t move yet so you won’t be able to see them falling down. Let’s implement the falling code to complete the entire spawning functionality!</p>
<h2 id="move-falling-objects">Move Falling Objects</h2>
<p>The last step for this chapter will be making the objects we are spawning fall to the ground. While building your very first <span>SpriteBuilder</span> game you have learned to use the <span>Cocos2D</span> action system to move nodes. The action system lets us describe changes over time, e.g. <em>move 100 points to the right over 2 seconds</em>. Another option to move nodes that we haven’t discussed yet is using the <span>Cocos2D</span> <em>update loop</em>.</p>
<h3 id="update-loop">Update Loop</h3>
<p>When we build games with <span>Cocos2D</span> the engine attempts to render 60 frames a second and draws theses rendered frames to the screen of the device. 60 discrete updates a second are so fast, that they appear as one continous movement to the human eye.</p>
<p>When we move objects between rendering frames, they will appear as moving objects to the user. <span>Cocos2D</span> provides a method that is called directly before a frame is rendered, the <span>update</span> method.</p>
<p>The <span>update</span> method is defined as part of the <span>CCSchedulerTarget</span> protocol. <span>CCNode</span> implements this protocol, that means any subclass of <span>CCNode</span> can override the method. This is the signature of the <span>update</span> method:</p>
<pre><code>func update(delta: CCTime)</code></pre>
<p>We receive one parameter called <span>delta</span> from the <span>Cocos2D</span> framework. The delta parameter contains the milliseconds since the <span>update</span> method was called last. Most of the time this value will be <em>0.0167</em> milliseconds, which is 1/60 of a second. If the performance of our game drops below 60 FPS this value will be higher, because the time between two rendered frames will increase. If we want our objects to move at the same speed, independent of the current framerate, we can use this delta parameter to calculate how far we need to move nodes between two given frames.</p>
<p>Enough of the theory - let’s implement our update method, that will help you understand the details.</p>
<h3 id="implementing-the-update-method">Implementing the Update Method</h3>
<p>Here is what we want to do in the update method:</p>
<ul>
<li><p>Iterate over all falling objects</p></li>
<li><p>For each object check if it is within the screen boundaries</p></li>
<li><p>If the object is outside of the screen, remove it</p></li>
<li><p>If the object is inside of the screen boundary, let it fall to the bottom</p></li>
</ul>
<p>Add the following <span>update</span> method to <span>MainScene</span>:</p>
<pre><code>  override func update(delta: CCTime) {
    // use classic for loop so that we can remove objects while iterating over the array
    for (var i = 0; i &lt; fallingObjects.count; i++) {
      let fallingObject = fallingObjects[i]
      
      // check if falling object is below the screen boundary
      if (CGRectGetMaxY(fallingObject.boundingBox()) &lt; CGRectGetMinY(boundingBox())) {
        // if object is below screen, remove it
        fallingObject.removeFromParent()
        fallingObjects.removeAtIndex(i)
      } else {
        // else, let the object fall with a constant speed
        fallingObject.position = ccp(
          fallingObject.position.x,
          fallingObject.position.y - CGFloat(fallingSpeed * delta)
        )
      }
    }
  }</code></pre>
<p>The interesting aspect of the code snippet above is how we check if the falling object is out of bounds and how we move the falling object. Note that we are using the <span>CGRectGetMaxY</span> and <span>CGRectGetMinY</span> functions to determine the top and the bottom of the bounding boxes of the falling object and the gameplay scene. The <span>CGRectGetMaxY</span> function returns the largest Y value of the bounding box. Using these functions is preferred over accessing values directly (e.g. <span>fallingObject.boundingBox.origin.y</span>) because they also work for rectangles with negative sizes, e.g. a rectangle with a height of <em>-10</em> (which is technically possible in 2D math!).</p>
<p>If we detect that the top border of the falling object is below the bottom border of the screen, we remove the falling object from the scene. We do that by first calling <span>removeFromParent</span> on the node - which removes it from the scene graph and makes it invisible. Then we additionally remove the node from the <span>fallingObjects</span> array, so that the node gets destroyed and the memory gets freed.</p>
<p>If the falling object is within the screen boundary we move it to the bottom with the constant speed that we defined earlier multiplied by the value of <span>delta</span>.</p>
<p>Now the falling mechanic is entirely implemented! In the next and last section of this chapter you will learn how to add sound assets to the game.</p>
<p>[Update vs. Fixed Update] This chapter discusses the <span>update:</span> method of <span>Cocos2D</span> in detail. <span>Cocos2D</span> provides a second similar method called <span>fixedUpdate:</span>. Unlike the <span>update:</span> method, the <span>fixedUpdate:</span> method is <strong>guaranteed</strong> to be called at a specified interval (per default 1/60) and is not dependent on the framerate the game is running at. The physics engine integrated in <span>Cocos2D</span> uses the <span>fixedUpdate:</span> method to perform all of its calculations. For you as developer that means that you should implement code that changes physical attributes in the <span>fixedUpdate:</span> method and <strong>not</strong> in the <span>update:</span> method. Building games involving physics is not part of this book. If you pursue a physics game on your own after finishing this book you can read a nice blog post about the <span>fixedUpdate</span> method here: <a href="http://kirillmuzykov.com/update-vs-fixedupdate-in-cocos2d/" class="uri">http://kirillmuzykov.com/update-vs-fixedupdate-in-cocos2d/</a>.</p>
<h2 id="adding-sound-effects">Adding Sound Effects</h2>
<p>The goal of this chapter is for you to learn how to use assets with <span>SpriteBuilder</span> and <span>Cocos2D</span>. Obviously images are the most important assets in games, but sound effects also play a big role in creating games that your players enjoy. In this section you will learn how to add a sound effect that gets played whenever one of the falling objects drops off the screen.</p>
<p><span>SpriteBuilder</span> is designed to take care of your entire asset management. This means that you want to add all image files and all audio files to your <span>SpriteBuilder</span> project.</p>
<p>All sound files need to be added to <span>SpriteBuilder</span> projects in the <em>Wave</em> format. <span>SpriteBuilder</span> will then generate compressed versions of that sound as you publish the project. You can add the sound effect - just like any other asset - by dragging it from Finder to the resource pane (in the bottom left) of <span>SpriteBuilder</span>. For this project I have included a <span>drop.wav</span> file in the <span>assets</span> folder that you downloaded and added to your project earlier.</p>
<p>There are different ways to play sound effects added to your <span>SpriteBuilder</span> project: you can add a sound effect to a <span>SpriteBuilder</span> timeline or you can play a sound effect directly from code. We will first look at the timeline approach, later in the book I will show you how to play sound effects in code. Before we set up the sound effect I want to give you a basic introduction to the timeline feature of <span>SpriteBuilder</span> since it is one of the most powerful tools that <span>SpriteBuilder</span> provides.</p>
<h3 id="spritebuilders-timeline-feature"><span>SpriteBuilder</span>’s Timeline Feature</h3>
<p>The <span>SpriteBuilder</span> timeline is a tool that allows developers to create animations and sequences of sound effects without writing code. Every <span>CCB File</span> has one <em>Default Timeline</em> associated with it as soon as it is created. However, a <span>CCB File</span> can, and often will, have multiple different timelines. Each timeline is a sequence of sound effects, callbacks and most importantly keyframes. Keyframes allow us to create animations by defining how sprites move and change over time. We can change properties such as position, rotation, color, etc. <span>SpriteBuilder</span>’s animation tool is very similar to the famous Flash keyframe editor. It is extremely useful in creating polished games and throughout later parts of this book we will use the <span>SpriteBuilder</span> timeline to create UI and game animations.</p>
<p>Timelines can either be idle or playing. Timelines start playing in one of three cases:</p>
<ol>
<li><p><em>Autoplay</em> is activated. That’s the default setting for the <em>Default Timeline</em></p></li>
<li><p>The timeline is triggered to play from code</p></li>
<li><p>The timeline has been chained to another timeline</p></li>
</ol>
<p>We’ll discuss each of these three cases as we use the timeline feature throughout this book.</p>
<p>You will get to know the value of <span>SpriteBuilder</span>s timeline as we add more features to our game.</p>
<h4 id="adding-the-sound-effect-to-a-timeline">Adding the sound effect to a timeline</h4>
<p>For now let’s take a look at how we can play sound effects using the timeline!</p>
<p>Start by creating a new timeline for the sound effect as shown in the following screenshot:</p>
<div class="figure">
<img src="images/Chapter2/new_timeline_audio.png" alt="WAV files can be added by dragging them to the resource pane" />
<p class="caption">WAV files can be added by dragging them to the resource pane<span data-label="fig:audionewtimeline"></span></p>
</div>
<p>Now we can add the audio file to this new timeline.</p>
<p>Take a look at the next image and follow the individual steps below it:</p>
<p><img src="images/Chapter2/audio_timeline.png" alt="image" /></p>
<dl>
<dt>(1)</dt>
<dd><p>Drag the sound effect from the asset library in the left panel to the <em>Sound effects</em> row of <span>SpriteBuilder</span>’s timeline (the second row from the top). When the sound is added to the timeline it will be displayed in wave form.</p>
</dd>
<dt>(2)</dt>
<dd><p>You should adjust the duration of the timeline to match the duration of the sound effect. Click onto the time indicator to adjust the timeline duration.</p>
</dd>
<dt>(3)</dt>
<dd><p>In the popup that shows up next, change the timeline duration to 10 frames.</p>
</dd>
</dl>
<p>Now the sound is ready to play! The last step is assigning a unique name to this timeline which we can reference from code. You can rename a timeline by either choosing <em>Animation -&gt; Edit Timelines…</em> or selecting the dropdown button next to the timeline name.</p>
<p>Rename the sound timeline to <em>DropSound</em>[timeline<sub>r</sub>ename].</p>
<ol>
<li><p>Open the timeline editor dialog:</p>
<p><img src="images/Chapter2/edit_timeline.png" alt="image" /></p></li>
<li><p>Then rename the timeline by double-clicking onto the name:</p>
<p><img src="images/Chapter2/rename_timeline.png" alt="image" /></p></li>
</ol>
<p>Now everything is set up and you can hit the publish button in <span>SpriteBuilder</span>.</p>
<p>Publish the <span>SpriteBuilder</span> project and switch to <span>Xcode</span>.</p>
<h3 id="triggering-a-sound-effect">Triggering a Sound Effect</h3>
<p>Now we have set up the sound effect in <span>SpriteBuilder</span> and published the project, all that is left to do is to open the <span>Xcode</span> project and add code to play the sound effect as soon as an object falls below the screen boundary.</p>
<p>We are going to implement this in <em>SBBMainScene.m</em>. <span>Cocos2D</span> provides a very simple API call to run a timeline animation from code. The following line added to <span>SBBMainScene</span> will run the timeline animation and thus play the sound we added to the project:</p>
<pre><code>animationManager.runAnimationsForSequenceNamed(&quot;DropSound&quot;)</code></pre>
<p>The animation manager of the root node of a <span>CCB File</span> provides us access to the different timelines and allows us to run and pause them and to react to their completion - we will use these capabilities extensively throughout this book.</p>
<p>As mentioned earlier we want to play the sound effect when an object falls off the screen. We already have code that checks for that condition in our <span>update</span> method. All we need to do this to add the line that runs the timeline.</p>
<p>Extend the relevant part of the <span>update</span> method to look as following:</p>
<pre><code>// check if falling object is below the screen boundary
if (CGRectGetMaxY(fallingObject.boundingBox()) &lt; CGRectGetMinY(boundingBox())) {
	// if object is below screen, remove it
    fallingObject.removeFromParent()
    fallingObjects.removeAtIndex(i)
    // play sound effect
    animationManager.runAnimationsForSequenceNamed(&quot;DropSound&quot;)
} else {...}</code></pre>
<p>Now you can compile and test the project. Every time an object falls of the screen you should hear the drop sound play!</p>
<h2 id="summary-1">Summary</h2>
<p>In this chapter you have learned how to work with an essential component of all video games - image and audio assets. You have learned how to design scenes with sprites in <span>SpriteBuilder</span>, and how to load and change sprite textures in code. You got to know how <span>SpriteBuilder</span> handles different asset resolutions for different screen and device types and you have played your first sound effect. You have learned some of the most important essentials of game development with <span>SpriteBuilder</span> and <span>Cocos2D</span>.</p>
<p>The focus of the next chapter is <em>User Interaction</em>. You will learn how to incorporate user input into your game by implementing a drag and drop mechanism!</p>
<h1 id="user-interaction">User Interaction</h1>
<p>In this chapter we will incorporate User Interaction into our game. First, we will add the player’s avatar, the pot, to the game. Then we will be implementing a drag and drop mechanism that lets the user move that pot in order to catch objects.</p>
<p>While implementing the drag and drop feature you’ll learn how <span>Cocos2D</span>’s touch system works in detail.</p>
<h2 id="add-the-pot-to-the-game">Add the Pot to the Game</h2>
<p>The goal of our game will be to move a pot across the screen and try to catch food while avoiding catching inedible objects. Before we can implement the drag and drop mechanism we need to add the pot assets to our game, we’re going to do that in the <span>SpriteBuilder</span> project.</p>
<p>Just as in the game we built in the very first chapter we are going to create an individual <span>CCB File</span> for this new entity. That way we can encapsulate its assets, behavior and animations nicely.</p>
<p>One important aspect of this game is the ability to for objects to fall into our pot. Since we are building a 2D game we need to fake the conception of depth in our scene. In <span>Cocos2D</span> we can use the z-order to influence which sprites are rendered in which order. Using that z-order, and using two assets for to create the pot, we can make it look like objects drop into the pot:</p>
<div class="figure">
<img src="images/Chapter3/drawing_order.png" alt="Left: Sprites rendered on different layers, Right: How the z-Order influences on which layer a sprite is rendered" />
<p class="caption">Left: Sprites rendered on different layers, Right: How the z-Order influences on which layer a sprite is rendered</p>
</div>
<p>It’s essential for this trick to break down the pot into two assets. Such rendering tricks are very common in 2D games!</p>
<h3 id="setting-up-the-pot-assets">Setting Up the Pot Assets</h3>
<p>Now that we know which assets we’ll use for the pot, let’s set up its <span>CCB File</span> in <span>SpriteBuilder</span>:</p>
<ol>
<li><p>Create a new <span>CCB File</span> of type <em>Node</em> and name it <em>Pot.ccb</em>:</p>
<p><img src="images/Chapter3/ccp_pot_file.png" alt="image" /></p></li>
<li><p>Open the new <span>Pot.ccb</span> file</p></li>
<li><p>Drag the <span>pot-top</span> and <span>pot-bottom</span> assets onto the root node of that <span>CCB File</span>:</p>
<p><img src="images/Chapter3/drag_pot_assets.png" alt="image" /></p></li>
<li><p>Select the root node and set the <em>Content Size</em> to (109, 75) and the <em>Anchor Point</em> to (0.5, 0.5)</p></li>
<li><p>Select the <em>pot-top</em> sprite from the timeline and set the <em>Position Type</em> to <em>Percent of Parent Container</em>, for both <em>X</em> and <em>Y</em>. Then set the position to <em>(50, 50)</em>:</p>
<p><img src="images/Chapter3/pot_top_position.png" alt="image" /></p></li>
<li><p>Select the <em>pot-bottom</em> sprite from the timeline and set up the same position as for <em>pot-top</em></p></li>
<li><p>Finally, use the shortkey <em>CMD+S</em> to save this <span>CCB File</span>. That will prevent a little rendering bug in the next step</p></li>
</ol>
<p>The result should be a pot that is centered on stage! You might wonder why we are setting an explicit size for the root node of <span>Pot.ccb</span>. We do that because that root node will be used to test against touch positions when we implement the dragging mechanism. Therefore we want that root node to have the same dimensions as the pot assets.</p>
<p>In a second we’re going to move on and implement the touch handling code. First however, we need to add the pot that we created to the <span>MainScene.ccb</span> file. <span>SpriteBuilder</span> allows us to add a <span>CCB File</span> to other <span>CCB File</span> - that’s an extremely useful feature as it allows us to reuse components in different scenes.</p>
<p>We’ll also need to set up a code connection, so that we can access the pot from our codebase when implementing the drag and drop mechanism later on!</p>
<ol>
<li><p>Open <span>MainScene.ccb</span></p></li>
<li><p>Drag the <span>Pot.ccb</span> file from the left panel onto the root node in the timeline of <span>MainScene.ccb</span>:</p>
<p><img src="images/Chapter3/drag_pot_ccb.png" alt="image" /></p></li>
<li><p>Set the <em>Position Type</em> of the pot to <em>Percent of parent container</em> for the <em>X</em> component</p></li>
<li><p>Set the <em>Position</em> to <em>(50, 58)</em></p></li>
<li><p>Select the pot, open the <em>Code Connections</em> tab in the right panel and set up a connection to the <em>Doc root var</em> named <em>pot</em>:</p>
<p><img src="images/Chapter3/pot_cc.png" alt="image" /></p></li>
<li><p>Finally, publish the <span>SpriteBuilder</span> project!</p></li>
</ol>
<p>Now we can move to the <span>Xcode</span> project to set up the code connection variable we just defined in <span>SpriteBuilder</span>. Then we’re ready to implement the touch handling code!</p>
<p>Open <span>MainScene.swift</span> and add properties for our code connection at the top of the class:</p>
<pre><code>weak var pot: CCSprite!</code></pre>
<p>There are three important things to remember about this code connection.</p>
<p>Firstly, all code connections should be marked as <span>weak</span>. <span>MainScene</span> has a reference to the pot sprites but does not <em>own</em> them. Instead they are owned by their parent node. For any references that don’t mark an ownership, <span>weak</span> should be used.</p>
<p>Secondly, we always want to declare code connections as <em>forcefully unwrapped optionals</em> as denoted by the bang (!) after the type. Swift requires that all properties that aren’t optionals are either initialized with a default value or get set to a value in one of the initializers of the class. That way the compiler can guarantee that these variables never contain a <span>nil</span> value. Code connections however are set up after the object is initialized (they are guaranteed to be set up when <span>didLoadFromCCB</span> is called on the node), so technically these should be optional values. Adding a lot of code for <span>nil</span> checking would clutter our classes, that’s why we prefer using the bang notation which basically says: <em>I am confident that this value will never be nil when I am trying to access it</em>. This is true for code connections as we know that <span>Cocos2D</span> guarantees to have set them up by the time <span>didLoadFromCCB</span> is called.</p>
<p>Lastly, be careful not to mark these variables as <span>private</span>. Otherwise <span>Cocos2D</span> will not have access to them and won’t be able to set up the code connections.</p>
<p>Okay, now we have the basics set up and are ready to dive into the details of implementing a drag and drop mechanism!</p>
<h2 id="implement-a-drag-and-drop-mechanism">Implement a Drag and Drop Mechanism</h2>
<p>For the very first project in this book we have already implemented a basic touch mechanism. You should remember that <span>userInteractionEnabled</span> is the property that activates/deactivates touch handling for a node and that <span>Cocos2D</span> provides four different callbacks for different state transitions in the lifecycle of a touch. Here’s the recap:</p>
<dl>
<dt>touchBegan:</dt>
<dd><p>called when a touch begins</p>
</dd>
<dt>touchMoved:</dt>
<dd><p>called when the touch position of a touch changes</p>
</dd>
<dt>touchEnded:</dt>
<dd><p>called when a touch ends because the user stops touching the screen</p>
</dd>
<dt>touchCancelled:</dt>
<dd><p>called when a touch is cancelled because user moves touch outside of the touch area of a node</p>
</dd>
</dl>
<p>Knowing that, how can we implement a drag and drop control scheme for our game? Dragging and dropping includes three different steps:</p>
<ol>
<li><p>Pick up object</p></li>
<li><p>Drag object</p></li>
<li><p>Drop object</p></li>
</ol>
<h3 id="picking-up-an-object">Picking Up an Object</h3>
<p>In order to pick up an object we need to detect a user’s touch and determine if the touch is within the boundaries of our object, if that is the case, we start dragging the object.</p>
<p>First of all, let’s turn on user interaction for the <span>MainScene</span> class, so that we receive touch events.</p>
<p>Add the required line to the <span>onEnterTransitionDidFinish</span> method:</p>
<pre><code>  override func onEnterTransitionDidFinish() {
    super.onEnterTransitionDidFinish()
    
    (*@\colorbox{light-gray}{userInteractionEnabled = true}@*) 
    
    // spawn objects with defined frequency
    schedule(&quot;spawnObject&quot;, interval: spawnFrequency)
  }</code></pre>
<p>Next, we need to add the touch handling method. The touch handling method will need to check if the touch is within our pot. If that is the case, the method will need to set a state variable that remembers that we are currently dragging this object. If the user moves a finger across the screen and we are currently in object dragging mode, it is important that the object follows the finger of the user.</p>
<p>Add this implementation to <span>MainScene.swift</span>:</p>
<pre><code>  override func touchBegan(touch: CCTouch, withEvent event: CCTouchEvent) {
    if (CGRectContainsPoint(pot.boundingBox(), touch.locationInNode(self))) {
      isDraggingPot = true
      dragTouchOffset = ccpSub(pot.anchorPointInPoints, touch.locationInNode(pot))
    }
  }</code></pre>
<p>Let’s discuss this implementation briefly. You already have seen the usage of <span>touch.locationInNode(self)</span> in the first chapter of this book, where we briefly discussed touch handling ([Introduction<sub>F</sub>irstTouchHandling]). This method returns the touch position within a given node. In this specific case we are receiving the touch position within <span>MainScene</span>.</p>
<p>Next, we are using a utility function, <span>CGRectContainsPoint</span>, to check if this touch is within the pot’s bounding box. <span>CGRectContainsPoint</span> takes a rectangle as its first argument and a point as its second. It returns true if the point is within the rectangle.</p>
<p>If the touch position is inside of the pot, we set our state variable, <span>isDraggingPot</span>, to <span>true</span>.</p>
<p>There is one last line that we didn’t discuss upfront:</p>
<pre><code>dragTouchOffset = ccpSub(pot.anchorPointInPoints, touch.locationInNode(pot))</code></pre>
<p>In order to drag an object smoothly we need to remember where we touched that object when starting dragging. Take a look at the following diagram:</p>
<div class="figure">
<img src="images/Chapter3/dragging_offset.png" alt="Top Image: incorrect implementation, object jumps to touch position. Bottom Image: correct implementation, touch offset is maintained while dragging the object." />
<p class="caption"><em>Top Image:</em> incorrect implementation, object jumps to touch position. <em>Bottom Image:</em> correct implementation, touch offset is maintained while dragging the object.<span data-label="userinteractiontouchoffset"></span></p>
</div>
<p>As the user moves the finger, we move the object along. However, the position of the object is not exactly the touch position. Instead it is the touch position <em>plus</em> the touch offset determined when we started dragging. We determine that offset by calculating the distance between the anchor point (that’s the reference point for positioning a node, typically it’s in the center of the node) of the touched object and the exact touch position. We calculate that distance by subtracting the touch location from the anchor point location using the <span>ccpSub</span> function.</p>
<p>Now we know why it is important to store the touch offset!</p>
<p>To wrap up the implementation of <span>touchBegan</span> let’s add the two properties we have referenced: <span>isDraggingPot</span> and <span>dragTouchOffset</span>. Your list of properties should now look like this:</p>
<pre><code>  weak var pot: CCSprite!
  
  private var fallingObjects = [FallingObject]()
  private let fallingSpeed = 100.0
  private let spawnFrequency = 0.5}
  (*@\colorbox{light-gray}{private var isDraggingPot = false}@*)
  (*@\colorbox{light-gray}{private var dragTouchOffset = ccp(0,0)}@*) </code></pre>
<h3 id="moving-an-object">Moving an Object</h3>
<p>Now we’ll implement the code that actually moves the pot. That code needs to run whenever a user’s finger moves. That means we need to implement the <span>touchMoved</span> method.</p>
<p>Add the <span>touchMoved</span> method below the <span>touchBegan</span> method:</p>
<pre><code>  override func touchMoved(touch: CCTouch, withEvent event: CCTouchEvent) {
    if (!isDraggingPot) {
      return
    }
    
    var newPosition = touch.locationInNode(self)
    // apply touch offset
    newPosition = ccpAdd(newPosition, dragTouchOffset);
    // ensure constant y position
    newPosition = ccp(newPosition.x, pot.positionInPoints.y);
    // apply new position to pot
    pot.positionInPoints = newPosition;
  }</code></pre>
<p>In the first line we check if we are currently in dragging mode. If not, we do nothing and return immediately. This prevents the pot from jumping to the latest touch position if it has not been picked up beforehand.</p>
<p>If we are in dragging mode we continue. First we get the new touch position. Then we apply the offset that we discussed in figure [user<sub>i</sub>nteraction<sub>t</sub>ouch<sub>o</sub>ffset] to that new position. The next line ensures that the y position of the pot stays constant, we want to allow horizontal movement only. Finally, we apply that new position to both pot parts.</p>
<p>Great, we’re pretty close to finishing the drag and drop functionality. If you test the app in the current state you’ll might see that there’s one simple yet important step missing…</p>
<h3 id="dropping-an-object">Dropping an Object</h3>
<p>Right, the user will also want to drop the pot by releasing the finger from the screen.</p>
<p>Otherwise we stay in dragging mode forever and the pot will keep jumping to whichever position the user taps on the screen. That kind of teleporting would turn this game into a very simple one!</p>
<p>Luckily this can be easily implemented. All we need to do is to set <span>isDraggingPot</span> to false as soon as the user stops touching the screen.</p>
<p>Add the <span>touchEnded</span> method below the <span>touchMoved</span> method:</p>
<pre><code>  override func touchEnded(touch: CCTouch, withEvent event: CCTouchEvent) {
    isDraggingPot = false
  }</code></pre>
<p>Awesome! Our drag and drop code is complete!</p>
<h2 id="summary-2">Summary</h2>
<p>Throughout this chapter you have implemented a drag and drop mechanism, while learning more details about the <span>Cocos2D</span> touch system. Drag and drop mechanisms can be used in many types of games, so what you have learned in this chapter is very valuable.</p>
<p>Now we can move on to the next chapter. We will implement one of the core mechanics of our game - catching objects. In the next chapter you’ll also learn some interesting tricks and details about scene graphs and node transforms.</p>
<h1 id="scene-graphs-node-transforms-and-state-machines">Scene Graphs, Node Transforms and State Machines</h1>
<p>In this chapter we will implement the catching mechanism for our game. This will require you to learn more details about scene graphs, node transforms and also about modelling game mechanics in Swift.</p>
<p>You will learn how to incorporate state machines into games. You will also learn how to detect if objects have been caught or not and how to manipulate the scene graph make objects fall into our catching pot.</p>
<p>There’s lots of work ahead of us!</p>
<h2 id="catching-objects">Catching Objects</h2>
<p>Implementing drag and drop was a great warm up. In this section we are going to solve a bunch of problems that will bring our little project a large step closer to being a real game. By the end of this section the user will be able to catch and miss objects by dragging the pot with the right timing.</p>
<p>Before we dive into coding let’s think about what we actually need to implement. There are three important aspects that need to be covered through our implementation:</p>
<ol>
<li><p>detecting if the user has caught an object</p></li>
<li><p>detecting if the user has missed an object</p></li>
<li><p>visualizing catching / missing correctly</p></li>
</ol>
<h3 id="thinking-in-states">Thinking in States</h3>
<p>Our feature outline describes that objects start out as falling objects, directly after they have been spawned. At some later point in time the user can catch or miss these objects. In each of these situations we need our falling objects to behave differently. If they are falling we want them to move down the screen with a constant speed. If they are caught we need some sort of visualisation - ideally the objects move into the pot and disappear. If the user tries to catch an object too late and misses it closely we want to visualize that, too.</p>
<p>From the paragraph above we can extract three different states in which a falling object can be:</p>
<div class="figure">
<img src="images/Chapter3/falling_object_states.png" alt="Objects start in falling state, then they end up caught or missed" />
<p class="caption">Objects start in falling state, then they end up caught or missed</p>
</div>
<p>As the diagram shows, a falling object can either stay a falling object or turn into a caught or missed object. It is up to us developers to decide the criteria for a state change. We also need to decide when we want to check for state changes.</p>
<p>For our game I suggest that we check whether a player has caught an object or not in the <span>update</span> method. As soon as that object reaches the y position of the top of the pot we decide based on the x position whether the object has been caught or missed</p>
<div class="figure">
<img src="images/Chapter3/catch_test.png" alt="Caught objects fall into the pot, missed objects fall behind" />
<p class="caption">Caught objects fall into the pot, missed objects fall behind<span data-label="CaughtMissedDefinition"></span></p>
</div>
<p>Since we are building a 2D game we only have limited ways of expressing that a player missed a falling object - I suggest that we render missed objects behind the pot. That way players can quickly see whether they caught an object or not.</p>
<p>Now we have a good starting point for some coding; we need to store different states for falling objects and we need to write specific behavior code for each of these states. Additionally we need to write code that checks if we have caught or missed an object so that we can assign the correct states to falling objects.</p>
<h3 id="storing-state">Storing State</h3>
<p>Now it’s time to implement the theoretical conctepts that we’ve discussed. Let’s start by adding a <span>fallingState</span> to <span>FallingObject.swift</span>. That state variable will remember whether an object is currently falling, has been caught or has been missed.</p>
<p>The best way to represent states in Swift is to use an enumeration!</p>
<p>Add this enum definition to <span>FallingObject.swift</span> below the <span>FallingObjectType</span> enum:</p>
<pre><code>  enum FallingObjectState {
    case Falling
    case Caught
    case Missed
  }</code></pre>
<p>As mentioned earlier, associating enum entries with a type is not mandatory. In this case our entries don’t need a type (e.g. Int) since the entries will only represent a state - they are values in their own right.</p>
<p>Next, add a property to store the current state:</p>
<pre><code>  var fallingState = FallingObjectState.Falling</code></pre>
<p>This variable should not be private, we want to change the value as the object gets caught or missed. Our default state is <span>.Falling</span>, we assign it as part of the variable declaration.</p>
<p>Now we can store a <span>fallingState</span> for each falling object; next, let’s implement different behaviour based on that state.</p>
<h3 id="implement-state-specific-behaviour">Implement State Specific Behaviour</h3>
<p>The majority of our gameplay code is currently inside of the <span>update</span> method of <span>MainScene</span>. This is fairly common for simple games. Currently we are doing two things in the update method: moving the objects down the screen and checking whether they have left the stage entirely (in which case we delete them). Now however, we are going to add code that will only run for falling objects in certain states. That will add quite a lot of complexity. Instead of squashing everything into the update method I suggest that we create one method for each of the three states. These methods will contain all state specific code and will be called from within the <span>update</span> method.</p>
<p>Replace your existing update method with the following one:</p>
<pre><code>    override func update(delta: CCTime) {
    // use classic for loop so that we can remove objects while iterating over the array
    for (var i = 0; i &lt; fallingObjects.count; i++) {
      let fallingObject = fallingObjects[i]
      
      // let the object fall with a constant speed
      fallingObject.position = ccp(
        fallingObject.position.x,
        fallingObject.position.y - CGFloat(fallingSpeed * delta)
      )
      
      switch fallingObject.fallingState {
      case .Falling:
        performFallingStep(fallingObject)
      case .Missed:
        performMissedStep(fallingObject)
      case .Caught:
        performCaughtStep(fallingObject)
      }
    }
  }</code></pre>
<p>Now the update method is really easy to read. We loop over all falling objects. In all cases we move the falling object towards the bottom of the screen. After that we check in which state an object is and invoke a method that contains code specific to that state. We are going to implement these methods throughout the remainder of this chapter.</p>
<h3 id="implementing-the-falling-state">Implementing the Falling State</h3>
<p>Let’s start implementing the default state: falling. In this state we will need check whether an object has been caught, has been missed or simply remains falling.</p>
<p>In figure [CaughtMissedDefinition] we have illustrated what we consider a caught/missed object. So how can we implement this? Basically all we need to do is compare the frame of the falling object to the frame of the pot. However, there is one small issue. The frame of a <span>CCSprite</span> is always a rectangle that encloses the entire texture. Here’s what the dimensions of the frames of our pot and a falling object look like:</p>
<div class="figure">
<img src="images/Chapter3/frame_pot_falling_object.png" alt="The pot frame is too large to use it for collision detection" />
<p class="caption">The pot frame is too large to use it for collision detection</p>
</div>
<p>From the illustration above you can see that the frame of the pot is too large to use it for collision detection. It could easily happen that an object landing on the handle of the pot would still be considered a catch.</p>
<p>Instead of using the pot dimensions we will need to add a separate, smaller, node in <span>SpriteBuilder</span> that marks the catch area.</p>
<p>Open the <span>SpriteBuilder</span> project and open <span>Pot.ccb</span></p>
<div class="figure">
<img src="images/Chapter6/add_catch_container_2.png" alt="The size and position of this container will determine when objects are caught / missed" />
<p class="caption">The size and position of this container will determine when objects are caught / missed</p>
</div>
<ol>
<li><p>Add a plain <em>Node</em> from the node library and add it as a child to root node, as highlighted in the screenshot above. A short reminder: the easiest way to do this, is dragging the node from the node library into the timeline and dropping it on top of <em>pot-bottom</em> node.</p></li>
<li><p>Set up <em>Position Type</em>, <em>Position</em> and <em>Anchor Point</em> of the container, as shown in the image above</p></li>
<li><p>Because we want to reference this catch container in code you will need to set a code connection, too. Set the target to <em>Doc root var</em> and call the variable <span>catchContainer</span>:</p>
<p><img src="images/Chapter6/container_cc.png" alt="image" /></p></li>
<li><p>Since the container is now connected to the root node of <span>Pot.ccb</span>, through the <span>catchContainer</span> property, the root node needs a custom class that has that property. Select the root node and set the custom class to <span>Pot</span></p>
<p><img src="images/Chapter6/pot_cc.png" alt="image" /></p></li>
<li><p>Publish the <span>SpriteBuilder</span> project</p></li>
</ol>
<p>Next, we need to create the <span>Pot</span> class that we just referenced, along with its <span>catchContainer</span> property!</p>
<ol>
<li><p>Create a new Class in <span>Xcode</span> and name it <span>Pot</span>. Make it a subclass of <span>CCNode</span></p></li>
<li><p>Add the <span>catchContainer</span> property so that the class definition looks like this:</p>
<pre><code>  class Pot: CCNode {
  
    weak var catchContainer: CCNode!
  
  }
  </code></pre></li>
</ol>
<p>Now we have a reference container set up. That container will allow us to test if objects have been caught or dropped. Remember, all of this code will taking place in the <em>falling step</em> state.</p>
<p>We can now start implementing falling step method.</p>
<p>Add the method stub for the falling step to <span>MainScene.swift</span>:</p>
<pre><code>  func performFallingStep(fallingObject:FallingObject) {

  }</code></pre>
<p>Before we can dive into collision detection we will have to take a little detour and talk about node transformations. As part of the introduction to <span>Cocos2D</span> we have discussed that nodes are always positioned relative to their parent node (chapter: [Introduction<sub>C</sub>CNode]). The catch container that we just added in <span>SpriteBuilder</span> is a child of the <span>Pot</span> node. We chose that setup so that the catch container always moves together with the pot.</p>
<p>For our collision detection algorithm we want to compare the position of a falling object to the position of our catch container. <strong>Here the problem arises: falling objects and the catch container have different parent nodes, that means we cannot compare their positions and frames directly.</strong> Since the position is relative to the parent node, comparing nodes with different parents would resolve in unexpected behavior. Take the following illustration as an example:</p>
<div class="figure">
<img src="images/Chapter3/parent_transform.png" alt="Even though the two nodes illustrated above are close to each other, their position values are entirely different, since they are placed relative to different parents" />
<p class="caption">Even though the two nodes illustrated above are close to each other, their position values are entirely different, since they are placed relative to different parents</p>
</div>
<p>How can we work around this? Luckily <span>Cocos2D</span> exposes a couple of variables and methods that allows us to transform positions and frames between different <em>node spaces</em>. Each node lives in the <em>node space</em> of its parent. In our example the catch container is in the node space of the pot and the pot is in the node space of the main scene.</p>
<p>If we want to know the position and size of the catching container in the main scene node space, we need to apply the following transform:</p>
<pre><code>let containerWorldBoundingBox = CGRectApplyAffineTransform(
  catchContainer.boundingBox(), catchContainer.parent.nodeToParentTransform()
);</code></pre>
<p>We are transforming the bounding box of the catch container using the <span>nodeToParentTransform</span> of the catch container’s parent node (the pot). The <span>Cocos2D</span> documentation describes the <span>nodeToParentTransform</span> as following: <em>Returns the matrix that transform the node’s (local) space coordinates into the parent’s space coordinates.</em></p>
<p>This means after applying the transform we know the position of the catch container in the main scene space. With the dimensions of both nodes in the same space, we can perform the bounding box comparison.</p>
<p>If you are new to graphics programming this concept will likely seem a little confusing; frankly you won’t need it too often when working with <span>Cocos2D</span>. If you aren’t getting a hold of transforms yet, don’t worry about it!</p>
<p>[The role of transforms in graphics programming] Transforms are an essential part of all graphics engines - also of <span>Cocos2D</span>. When determining the positions for all nodes in a scene, <span>Cocos2D</span> starts with the root node. After the root node is laid out, the engine moves to the children of the root node, calculates their position and places them <em>relative to the root node</em>. This is repeated all the way down the node hierarchy:</p>
<p><img src="images/Chapter3/parent_transform_rendering.png" alt="image" /></p>
<p>Now that we have a solution for the transformation issue, the rest of the code that we need for the falling step is not too complicated.</p>
<p>First, change the type of our <span>pot</span> property from <span>CCSprite</span>to <span>Pot</span> so that we can access the <span>catchingContainer</span> property from within <span>MainScene</span>.</p>
<p>Change the code connection property <span>pot</span> within <span>MainScene.swift</span> to look like this:</p>
<pre><code>  weak var pot: Pot!</code></pre>
<p>Now we can implement the falling step method! Let’s first add the code and then discuss it in detail.</p>
<p>Replace the <span>performFallingStep</span> stub with this implementation:</p>
<pre><code>  func performFallingStep(fallingObject:FallingObject) {
    let containerWorldBoundingBox = CGRectApplyAffineTransform(
      pot.catchContainer.boundingBox(), pot.nodeToParentTransform()
    );
    
    let yPositionInCatchContainer = CGRectGetMinY(fallingObject.boundingBox()) &lt; CGRectGetMaxY(containerWorldBoundingBox)
    let xPositionLargerThanLeftEdge = CGRectGetMinX(fallingObject.boundingBox()) &gt; CGRectGetMinX(containerWorldBoundingBox)
    let xPositionSmallerThanRightEdge = CGRectGetMaxX(fallingObject.boundingBox()) &lt; CGRectGetMaxX(containerWorldBoundingBox)
    
    // check if falling object is inside catching pot, trigger this when object reaches top of pot
    if (yPositionInCatchContainer) {
      if (xPositionLargerThanLeftEdge &amp;&amp; xPositionSmallerThanRightEdge) {
        // caught the object
        let fallingObjectWorldPosition = fallingObject.parent.convertToWorldSpace(fallingObject.positionInPoints)
        fallingObject.removeFromParent()
        fallingObject.positionInPoints = pot.convertToNodeSpace(fallingObjectWorldPosition)
        pot.addChild(fallingObject)
        fallingObject.fallingState = .Caught
      } else {
        fallingObject.fallingState = .Missed
      }
    }
  }</code></pre>
<p>We have already discussed the first statement extensively, we transform the bounding box of our catch container. That allows us to compare its position to the position of falling objects.</p>
<p>The next three lines are each used to determine if the falling object is within the relevant boundaries of our transformed catch container. The <span>CGRectGetMin…</span> utility functions are used to get the lowest/highest value on a certain axis from the bounding box. These three statements check for the conditions outlined in figure [CaughtMissedDefinition]. If all three are true the player has caught the object.</p>
<p>Next, we have an if statement that combines the three boolean variables. The first if statement checks if the falling object is in the <em>critical area</em> using the <span>yPositionInCatchContainer</span> constant. Here the y position of the falling object is the only relevant metric. If we aren’t in the critical area we do nothing at all - the object is still too far above the pot for us to decide whether the player caught it or not.</p>
<p>If the object is in the critical area we now need to determine if it has been caught or missed. This is where we need the two x position variables. If the object is outside of the bounds we set the <span>fallingState</span> to <span>.Missed</span>.</p>
<p>If the object is inside of the bounds we set the <span>fallingState</span> to <span>.Caught</span>. Additionally we need to ensure that once the object is caught it stays within the pot. Without additional code the caught objects are not attached to the pot. The player could move the pot left or right and the objects would fall out to the side of the pot. As soon as an object is caught we need to turn it into a child node of the pot, that way they will stick together.</p>
<p>Here we once again need a transform. We want to turn the falling object into a child of the pot instead of being a child of main scene. That means we are moving the object to a different node space. We don’t want the player to see this move happen; visually the object should stay at exactly the same position.</p>
<p>In such situations we need to use a two step transform. First, we need to find the <em>world space</em> position of the node that we are moving to a different node space. The position in the world space is expressed relative to the world root (in most cases the bottom left corner of the screen) and not relative to the parent node. You can think of the position in world space as a global or absolute position. We can use the world position to find the corresponding relative position in any node space.</p>
<p>Let’s take a look at our specific code. First we call:</p>
<pre><code>let fallingObjectWorldPosition = fallingObject.parent.convertToWorldSpace(fallingObject.positionInPoints)</code></pre>
<p>This line asks: <em>What is the global position, independent of the parent node, of this falling object?</em> The node that receives this question needs to be the parent node of <span>fallingObject</span>, because that is the node responsible for placing the <span>fallingObject</span> node by applying its transform.</p>
<p>Now that we have saved the position, we remove the node from its parent. Next we perform the second step of the transformation:</p>
<pre><code>fallingObject.positionInPoints = pot.convertToNodeSpace(fallingObjectWorldPosition)</code></pre>
<p>This line asks: <em>Dear pot, I have a global position for this falling object, could you tell me what the relative position in your node space would need to be? I want the falling object to remain at the same global position after adding it to you as a child.</em> After we have determined the right position we finally add the falling object to the pot. The object will now switch to a different node space and become a child of the pot without that the player will realize it, awesome!</p>
<p>This was a pretty intense implementation so here’s recap what we did to implement the code that runs while our object is in the <em>falling state</em>:</p>
<ol>
<li><p>We added a catch container do define the area in which a player can catch objects. We did this because the frame of the entire pot is too large to serve as catch area</p></li>
<li><p>We transformed this catch container from the pot space into the main scene space. We did that because we need the falling object and the catch container to be in the same space in order to compare their positions</p></li>
<li><p>When we determine that an object has been missed we set the state of the falling object to <span>.Missed</span></p></li>
<li><p>When we determine that an object has been caught we set the state of the falling object to <span>.Caught</span>. Additionally we add the caught object as a child to the pot, to ensure that the object stays within the pot after it has been caught. Before we add the object as a child to the pot we use a two way transform to figure out the position the object needs to have as a child of the pot node</p></li>
</ol>
<p>This concludes almost all the features we need for the <em>falling</em> step. Later we will come back for some visual tweaks but for now we can move on to the missed state.</p>
<p>This is also a great time for a break and your favorite hot beverage!</p>
<h3 id="implementing-the-missed-state">Implementing the Missed State</h3>
<p>Good news: the remaining two steps are a lot simpler. We can implement the <em>missed</em> state by restructuring existing code:</p>
<p>Add the method for the <em>missed</em> step:</p>
<pre><code>  func performMissedStep(fallingObject:FallingObject) {
    // check if falling object is below the screen boundary
    if (CGRectGetMaxY(fallingObject.boundingBox()) &lt; CGRectGetMinY(boundingBox())) {
      // if object is below screen, remove it
      
      fallingObject.removeFromParent()
      let fallingObjectIndex = find(fallingObjects, fallingObject)!
      fallingObjects.removeAtIndex(fallingObjectIndex)
      // play sound effect
      animationManager.runAnimationsForSequenceNamed(&quot;DropSound&quot;)
    }
  }</code></pre>
<p>All of this code was part of the <span>update</span> method earlier. All we do here is move it into a separate method. As soon as an object is in the missed state we now that it has fallen below the pot opening and can be no longer caught. Now all we need to do is to wait until the object falls below the screen boundary, then we play our sound and remove it.</p>
<h3 id="implementing-the-caught-state">Implementing the Caught State</h3>
<p>The last state is the simplest of all. When we have caught an object we want to create the illusion of the object disappearing into the pot. The first step is adding the object as a child to the pot, we’ve already done that in the <em>falling</em> step.</p>
<p>All we need to do in the <em>caught</em> state is wait until the object disappears entirely inside of the pot; then we can remove it.</p>
<p>Add the method for the <em>caught</em> step:</p>
<pre><code>  func performCaughtStep(fallingObject:FallingObject) {
    // if the object was caught, remove it as soon as soon as it is entirely contained in the pot
    if (CGRectContainsRect(catchContainer.boundingBox(), fallingObject.boundingBox())) {
      fallingObject.removeFromParent()
      let fallingObjectIndex = find(fallingObjects, fallingObject)!
      fallingObjects.removeAtIndex(fallingObjectIndex)
    }
  }</code></pre>
<p>As soon as the catch container bounding box fully encloses the caught object we can remove it. For the player it will seem that the object disappeared into the inner darkness of our bottomless pot.</p>
<h3 id="time-to-test">Time to Test</h3>
<p>Now we’re finally back to a state where we can run and test the game. You should now be able to catch objects in the game.</p>
<p>The illusion of the objects disappearing in a pot isn’t really working at this point. All caught objects get rendered in front of the pot and then suddenly disappear.</p>
<p>Let’s fix this issue with a rendering tweak!</p>
<h2 id="a-rendering-tweak">A Rendering Tweak</h2>
<p>[rendering<sub>t</sub>weak]</p>
<p>In the previous chapter we’ve briefly discussed how the rendering order in <span>Cocos2D</span> works. In order to fix our issue we need to dive into some more details.</p>
<h3 id="working-with-the-z-order">Working with the Z-Order</h3>
<p>[z-order-intro] Throughout this book we are working with a 2D engine. In a 2D engine depth can only be represented by certain objects being placed in front or behind of other objects. <span>Cocos2D</span> uses the following criteria to decide which nodes are rendered in front of other nodes:</p>
<ol>
<li><p>Child nodes are rendered in front of their parent nodes</p></li>
<li><p>Siblings (nodes with the same parent) are rendered in order of their <span>zOrder</span> property; nodes with higher <span>zOrder</span> are rendered in front of nodes with a lower one</p></li>
<li><p>If two siblings have the same <span>zOrder</span> the siblings are rendered in reverse order of how they have been added (the latest added node is rendered in front of all other nodes)</p></li>
</ol>
<p>As you can see from the description above the <span>zOrder</span> only affects how siblings are ordered, <span>Cocos2D</span> currently does not have a global <span>zOrder</span>. For our game we want to create the illusion of objects dropping into a pot, we can do that using the <span>Cocos2D</span> z-order. Here’s a short reminder of how the z-order influences the rendering order:</p>
<div class="figure">
<img src="images/Chapter3/drawing_order.png" alt="Left: Objects on different Layers, Right: How the z-Order influences on which Layer a node is rendered" />
<p class="caption">Left: Objects on different Layers, Right: How the z-Order influences on which Layer a node is rendered</p>
</div>
<p>For this solution to work all the falling objects and the bottom and top part of our pot need to have the same parent node, otherwise we would not be able to use the z-Order to place the falling objects between the two parts of the pot.</p>
<p>You might remember, that we have already taken care of this issue by adding all caught objects to the pot node.</p>
<p>[Global Z-order in <span>Cocos2D</span>] While <span>Cocos2D</span> does not have support for global Z-order at the moment, it is being discussed as a potential feature for future releases. Many games run into issues as discussed above due to the lack of this feature. You can follow the discussion on GitHub: <a href="https://github.com/cocos2d/cocos2d-swift/issues/662" class="uri">https://github.com/cocos2d/cocos2d-swift/issues/662</a>.</p>
<p>At the point in time where an object is caught it has the same parent node as the top and bottom part of the pot - this means we can use the <span>zOrder</span> property of these nodes to solve our problem.</p>
<p>There’s a neat trick for managing the rendering order in a scene. We can use an enum in which each entry represents a different <em>layer</em> in the scene.</p>
<p>Add this enum definition to the <span>Pot</span> class:</p>
<pre><code>  enum DrawingOrder: Int {
    case PotTop
    case FallingObject
    case PotBottom
  }</code></pre>
<p>Here we are defining three different layers. Each of them haven an associated integer value that we can directly apply to the <span>zOrder</span> variable of our nodes. This enum describes that the <span>FallingObject</span> layer will be rendered in front of the <span>PotTop</span> layer. By using this enum technique we can easily change the rendering order in scenes without modifying a lot of code.</p>
<p>Next, we need to assign the <span>zOrder</span> values to their corresponding nodes. Let’s start with <span>PotTop</span> and <span>PotBottom</span>.</p>
<p>We will need some additional code connections to get access to the two different parts of the pot!</p>
<ol>
<li><p>Open the <span>Pot.ccb</span> file in <span>SpriteBuilder</span></p></li>
<li><p>Select the <em>pot-bottom</em> node and assign the following code connection:</p>
<p><img src="images/Chapter6/pot_bottom_code.png" alt="image" /></p></li>
<li><p>Select the <em>pot-top</em> node and assign this code connection:</p>
<p><img src="images/Chapter6/pot_top_code.png" alt="image" /></p></li>
<li><p>Publish the <span>SpriteBuilder</span> project!</p></li>
</ol>
<p>Now we can switch back to <span>Xcode</span> and initialize the pot with its correct z-order values.</p>
<p>First, we need to set up the properties for our code connections.</p>
<p>Add the following two properties to the <span>FallingObject</span> class:</p>
<pre><code>weak var potTop: CCNode!
weak var potBottom: CCNode!</code></pre>
<p>Then we can add the initializer.</p>
<p>Add this implementation of <span>didLoadFromCCB</span> that initializes the pots’ <span>zOrder</span> to the <span>Pot</span> class:</p>
<pre><code>func didLoadFromCCB() {
  potTop.zOrder = DrawingOrder.PotTop.rawValue
  potBottom.zOrder = DrawingOrder.PotBottom.rawValue
}</code></pre>
<p>Now we need to take care of the falling object. When it is caught, we want to render it between the two pot parts. For this we need to extend the code that marks objects as caught.</p>
<p>Add the relevant line to the <span>if</span> case of the <span>performFallingStep</span> method in the <span>MainScene</span> class:</p>
<pre><code>    ...
      if (// caught) {
        ...
        fallingObject.fallingState = .Caught
        fallingObject.zOrder = Pot.DrawingOrder.FallingObject.rawValue
      }
    ...</code></pre>
<p>Great! With this tweak we have completed a significant portion of the core gameplay.</p>
<h2 id="summary-3">Summary</h2>
<p>In this chapter we have completed what we call the <em>core mechanic</em> of our game. A player can drag the catching pot across the screen and collect items.</p>
<p>Along the way you have learned how to incorporate state machines into the codebase of your game. I hopefully could show that they are a great tool to structure your gameplay code.</p>
<p>You have also learnt how to transform node positions and sizes between different node spaces and how to work with the z-order to create a 3D feel in a 2D world.</p>
<p>To turn the core mechanic that we have built in this chapter into a game, we will need to add some rules and game modes. We will tackle that throughout the next chapter.</p>
<h1 id="user-interfaces-and-implementing-multiple-game-modes">User Interfaces and Implementing Multiple Game Modes</h1>
<p>So far we have made a lot of progress on the core mechanic of our game. Another important aspect are the screens and components that wrap this mechanic. In this chapter you will learn how to implement menus, popups and other user interface elements in <span>Cocos2D</span>.</p>
<p>Throughout this chapter you will not only learn how to build user interfaces with <span>Cocos2D</span> and <span>SpriteBuilder</span>, you will also learn how to structure this game to support two different gameplay modes. We will implement and <em>endless</em> and a <em>timed</em> gameplay mode, each with a different set of rules and behaviors. We will choose an architecture that will make it easy to add more game modes in future.</p>
<p>By the end of this chapter we will have a fully functional game! Here’s the basic screen flow our game will have:</p>
<p><img src="images/Chapter6/screen_flow.png" alt="image" /></p>
<p>Let’s start out by adding the game mode selection scene!</p>
<h2 id="adding-a-game-mode-selection-scene">Adding a Game Mode Selection Scene</h2>
<p>We will now change the screen flow of our existing game. Instead of diving into the gameplay directly the user will see a game mode selection scene when starting the game.</p>
<p>The game mode selection scene will allow the user to swipe to switch between the endless and timed game mode. Luckily <span>Cocos2D</span> provides a component called <span>CCScrollView</span> that implements most of the functionality that we need for that scene.</p>
<h3 id="setting-the-start-scene-up">Setting the Start Scene Up</h3>
<p>Open the <span>SpriteBuilder</span> project and create a new File (File -&gt; New -&gt; File…). Name the new file <em>StartScene</em> and select <em>Scene</em> as the type.</p>
<p>We will create a game mode select scene that smoothly transitions into the gameplay. To accomplish that we’ll use the same background image for this scene as for the actual gameplay.</p>
<p>Drag the image <em>backround.png</em> image onto the stage; it becomes the first child of the root node of our new <em>StartScene</em>.</p>
<p>The background image should have exactly the same settings as in <em>MainScene</em> so that it fills the entire scene.</p>
<p>Select the background sprite in the timeline and apply the following steps:</p>
<ol>
<li><p>Set the <em>Position type</em> for X and Y to <em>percent of parent container</em></p></li>
<li><p>Set the <em>Position</em> to <em>(50, 50)</em></p></li>
</ol>
<p>Now the background image should fill the entire background. We will be presenting some information in front of that background. To make that information stand out more we will dim the background a little bit by turning down its opacity. Since the default fill color behind the background image is black, a lower opacity will result in a darker image.</p>
<p>Select the background sprite in the timeline. Set the opacity in the property inspector to <em>0.7</em>:</p>
<p><img src="images/Chapter6/opacity_lower.png" alt="image" /></p>
<p>Next, we are going to add a label with an instruction for the player. A label is a simple UI component that can display text. When building games with <span>Cocos2D</span> we want to place the most UI components relative to screen edges. Using this approach the UI will still look good when the game runs on a device with a different screen size. Here’s a little illustration:</p>
<div class="figure">
<img src="images/Chapter6/multiple_screen_sizes.png" alt="UI elements should be placed relative to screen edges to preserve their position on different screen sizes" />
<p class="caption">UI elements should be placed relative to screen edges to preserve their position on different screen sizes</p>
</div>
<p>As the screen resizes, the visible portion of the gameplay changes while the button positions remain similar.</p>
<p>Throughout this chapter we will use <span>Cocos2D</span>’s reference corner feature to accomplish resizable user interfaces.</p>
<p>Drag a <em>CCLabelTTF</em> from the node library <em>below</em> the background sprite, so that is rendered on top of the background image:</p>
<p><img src="images/Chapter7/label_ontop_background.png" alt="image" /></p>
<p>Set the position up as following:</p>
<ol>
<li><p>Set the <em>Position Reference Corner</em> to <em>Top-left</em>:</p>
<p><img src="images/Chapter7/pos_ref_corner.png" alt="image" /></p></li>
<li><p>Set the position type for X to <em>percent of parent container</em></p></li>
<li><p>Set the X position to <em>50</em></p></li>
<li><p>Set the Y position to <em>80</em></p></li>
</ol>
<p>Set the label text to: <em>Choose your game mode:</em>. We also want to change the font and appearance of this label a little:</p>
<ol>
<li><p>As font name choose: <em>Optima-Bold</em></p></li>
<li><p>As font size choose: <em>40</em></p></li>
<li><p>Under <em>Font Effects</em>, set the draw color to <em>black</em></p></li>
<li><p>Set the outline color to <em>white</em></p></li>
<li><p>Set the outline width to <em>6</em></p></li>
</ol>
<p>After setting the label up your start scene should look as following:</p>
<p><img src="images/Chapter7/start_scene.png" alt="image" /></p>
<p>There’s a lot more work left to do! As mentioned earlier we will create a scroll view that let’s the user swipe between two different game modes. Every scroll view has a content node. That content node is larger than the size of the scroll view and the scroll view can be used to view different parts of this content node. Here’s an illustration:</p>
<div class="figure">
<img src="images/Chapter7/scrollview_concept.png" alt="The scroll view can present different portions of its larger content node. The user can change the displayed portion by swiping." />
<p class="caption">The scroll view can present different portions of its larger content node. The user can change the displayed portion by swiping.</p>
</div>
<p>Our next step will be creating this content node. In general scroll views allow users to scroll to any arbitrary position within the scroll view’s content node. In our specific example we would like to change this behavior. We only want the user to select between two different game modes, each of these game modes will be represented by a full screen node. It wouldn’t make sense to allow the user to scroll half way between the endless and timed game mode. For this specific case the scroll view provides an option called <em>Paging enabled</em>. If you want to use a scroll view with paging, your content node needs to have a size that is a multiple of the scroll view’s size. In our particular example the content node for our scroll view will be twice as wide as the scroll view itself, resulting in a scroll view with two pages. When paging is enabled, the scroll view will always snap to one of the two pages as soon as a user stops scrolling. If this sounds a little bit too abstract for you, it should become clearer as we implement and use the scroll view.</p>
<h3 id="creating-the-content-node-for-the-scroll-view">Creating the Content Node for the Scroll View</h3>
<p>First we need to create the content view. We will set it up in a separate <span>CCB File</span> file.</p>
<p>Create a new <span>CCB File</span> called <em>GameModeSelectLayer</em> and choose its type to be a <em>Layer</em>.</p>
<p>[Why are we using a Layer to create the scroll view content?] A short refresher on the different <span>CCB File</span> types: Scenes are used to represent full screen content. Sprites are used for simple Sprite Images. Nodes are used for node compositions that don’t have a specific content size. Layers are used to create content within a stage that has a fixed size. Layers are typically used for popups or scroll view content nodes because we want to layout the content based on a container size. We can still use parent-relative sizing for layers. For our scroll view content layer we will set a width that is <em>2x</em> the width of the parent container. As soon as that layer is added to another node, the final size of it will be determined based on the size of that parent node.</p>
<p>Change the size of the root node:</p>
<ol>
<li><p>Select the root node of <em>GameModeSelectLayer.ccb</em></p></li>
<li><p>Set the <em>Content Size Type</em> of the width and height to <em>percent of the parent container</em></p></li>
<li><p>Set the content size to <em>(200, 100)</em></p></li>
</ol>
<p><img src="images/Chapter7/content_node_width.png" alt="image" /></p>
<p>We want the scroll view to contain two pages, that means the content node needs to be exactly double as wide as the scroll view. Because we are setting up the size of the root node of this <span>CCB File</span> in percentage of the parent container, its actual size will only be determined when it is added to a scroll view. This is a great example of dynamic layouts; our scroll view could have any arbitrary size and this content node would always be exactly twice as wide.</p>
<p>Inside of this root node we are going to place the content for our two different pages. To provide a clean structure we will create one container node for each page.</p>
<p>Add the container node for the left page:</p>
<ol>
<li><p>Add a plain <span>CCNode</span> as a child to the root node of <span>GameModeSelectLayer.ccb</span></p></li>
<li><p>Name this child <em>endless-mode</em> by selecting the node in the timeline and hitting the return key</p></li>
<li><p>Set the <em>Content Size Type</em> to <em>Percent of parent container</em> for both <em>Width</em> and <em>Height</em></p></li>
<li><p>Set the <em>Content Size</em> to <em>(50, 100)</em></p></li>
</ol>
<p>The first page is set up; let’s add the second one.</p>
<p>Add the container node for the right page:</p>
<ol>
<li><p>Add a plain <span>CCNode</span> as a child to the root node of <span>GameModeSelectLayer.ccb</span></p></li>
<li><p>Name this child <em>timed-mode</em> by selecting the node in the timeline and hitting the return key</p></li>
<li><p>Set the <em>Content Size Type</em> to <em>Percent of parent container</em> for both <em>Width</em> and <em>Height</em></p></li>
<li><p>Set the <em>Content Size</em> to <em>(50, 100)</em></p></li>
<li><p>Additionally, set the <em>Position Type</em> for <em>X</em> to <em>Percent of parent container</em></p></li>
<li><p>Set the <em>Position</em> to <em>(50, 0)</em></p></li>
</ol>
<p>Now we have containers for each page set up. We are going to fill them with labels that describe the game mode represented on each page. We’ll also add an arrow indicating that there is another game mode available by swiping across the screen. This is what the completed content node will look like:</p>
<div class="figure">
<img src="images/Chapter7/content_node_completed.png" alt="The completed content node by the end of this section." />
<p class="caption">The completed content node by the end of this section.</p>
</div>
<p>First, let’s add the labels for the endless mode.</p>
<p>Add the label for the endless mode, it should ook the same as the <em>Choose your game mode</em> label on the start scene:</p>
<ol>
<li><p>Drag a <span>CCLabelTTF</span> from the node library onto the <em>endless-mode</em> node</p></li>
<li><p>Center the label within its parent node by choosing a <em>Position type</em> of <em>percentage of parent container</em></p></li>
<li><p>Set the <em>Position</em> to <em>(50, 50)</em></p></li>
<li><p>Set the label text to <em>Endless</em></p></li>
<li><p>As font name choose: <em>Optima-Bold</em></p></li>
<li><p>As font size choose: <em>40</em></p></li>
<li><p>Set the draw color to <em>black</em></p></li>
<li><p>Set the outline color to <em>white</em></p></li>
<li><p>Set the outline width to <em>6</em></p></li>
</ol>
<p>Next, let’s add the arrow on the right side that will indicate that the player can switch to the timed game mode.</p>
<p>Add an arrow to the <em>endless-mode</em> node:</p>
<ol>
<li><p>Copy and Past the <em>Endless</em> node</p></li>
<li><p>Change the label text to <em>&gt;&gt;</em></p></li>
<li><p>Set the position up as following:</p>
<p><img src="images/Chapter7/arrow_label_position.png" alt="image" /></p></li>
</ol>
<p>Now your stage should look like this:</p>
<p><img src="images/Chapter7/endless_mode.png" alt="image" /></p>
<p>We’re going to add a little visual detail to this game mode selection layer. The arrows indicating the other available game mode shall blink. This can be easily accomplished using <span>SpriteBuilder</span>’s timeline feature. The animation shall last one second, so start by changing the timeline duration.</p>
<p>Set the timeline duration to 1 second as illustrated in the image below:</p>
<div class="figure">
<img src="images/Chapter7/timeline_duration.png" alt="Changing the timeline duration" />
<p class="caption">Changing the timeline duration<span data-label="fig: timelineduration"></span></p>
</div>
<p>Now we are going to use three <em>opacity</em> keyframes to create the blinking animation.</p>
<p>Select the label with the arrows in the timeline. Then create three keyframes. Place the first keyframe at timestamp 00:00:00 the second one at timestamp 00:00:15 and the third one at timestamp 00:01:00. You can choose the exact position of a keyframe by dragging the timeline ruler to the according position. You can create keyframes by hitting the <em>O</em> (like in opacity) key on your keyboard. Alternatively you can create keyframes through the top bar menu: <em>Animation -&gt; Insert Keyframe…-&gt; Opacity</em>:</p>
<div class="figure">
<img src="images/Chapter7/timeline_ruler.png" alt="Drag the timeline ruler to select a frame at which you want to create the keyframe" />
<p class="caption">Drag the timeline ruler to select a frame at which you want to create the keyframe</p>
</div>
<p>Now we can set different opacity values for each of these keyframes and <span>SpriteBuilder</span> will create smooth animations between them. There are two ways to set a specific value for a keyframe. You can select the keyframe and change the relevant property in the property inspector in the right panel of <span>SpriteBuilder</span>. The easier way however is to double-click onto a keyframe. That will bring up a small popup in which you can modify the relevant values:</p>
<div class="figure">
<img src="images/Chapter7/edit_keyframe.png" alt="Double-click onto keyframes to modify their values" />
<p class="caption">Double-click onto keyframes to modify their values</p>
</div>
<p>Set the opacity in the first keyframe to 1.0. Set the opacity to 0.0 in the second keyframe. For the third keyframe set the opacity to 1.0 again.</p>
<p>Now the arrow will appear for half a second and then disappear for another half a second. We don’t want this animation to be over after 1 second. Instead we want to loop it forever. We can do so by <em>chaining</em> the timeline to itself. In <span>SpriteBuilder</span> timelines can be chained to each other. That means that you can define that another timeline should run after the current timeline is completed. If you use this feature to chain a timeline to itself you have an endlessly running timeline animation!</p>
<p>Chain the default timeline to itself as shown below:</p>
<div class="figure">
<img src="images/Chapter7/chain_timeline_2.png" alt="SpriteBuilder allows you to connect different animations by chaining timelines" />
<p class="caption"><span>SpriteBuilder</span> allows you to connect different animations by chaining timelines</p>
</div>
<p>[Looping animations in <span>SpriteBuilder</span>] Animations that are set up with a chained timeline will loop endlessly when your game is running on a simulator or phone. In <span>SpriteBuilder</span> itself the animation will only run once. If you want to preview what your animation will look like when it is looped, you need to use the following control in the timeline playback panel:</p>
<p><img src="images/Chapter7/loop_timeline.png" alt="image" /></p>
<p>Note that this control will only affect your previewed animation in <span>SpriteBuilder</span>. Not the actual animation running in your game.</p>
<p>Now we are finished setting up one of the two pages for our scoll view. Setting up the node for the timed game mode involves exactly the same steps as you have seen just now. The only difference is the arrow label and the caption of the game mode label.</p>
<p>The arrows should be pointing to the left and the arrow should be positioned from the left edge of the <em>timed-mode</em> node. The main label should say <em>Timed</em> instead of <em>Endless</em>.</p>
<p>I will leave this as an exercise to you. Remember that you can always check the solution on GitHub (<a href="https://github.com/SpriteBuilder-Book/Code" class="uri">https://github.com/SpriteBuilder-Book/Code</a>) if you get stuck. Once you have set up the node for the second game mode come back and we’ll integrate this game mode selection layer into the start scene.</p>
<p>Set up the second page of the <em>GameModeSelectLayer</em>. You’ll be the fastest if you copy and past the labels from the first page.</p>
<p>Once you are done, your solution should look like this:</p>
<p><img src="images/Chapter7/sv_result.png" alt="image" /></p>
<p>Now we’re ready to integrate this content node into a scroll view!</p>
<p>Add a scroll view to <em>StartScene.ccb</em>:</p>
<ol>
<li><p>Open the <em>StartScene.ccb</em> file</p></li>
<li><p>Drag a <em>Scroll View</em> from the node library to the timeline of <em>StartScene.ccb</em> and drop it <strong>below</strong> (not on top of!) the <em>background</em> node in the timeline (so that the scroll view is rendered in front of the background image)</p></li>
<li><p>Set the <em>Position</em> to <em>(0,0)</em></p></li>
<li><p>The scroll view shall cover the entire screen, so set the <em>Content size type</em> to <em>Percent of parent container</em> for both <em>Width</em> and <em>Height</em></p></li>
<li><p>Set the <em>Content Size</em> to <em>(100, 100)</em></p></li>
<li><p>Set up the scroll view specific settings in the property inspector as follows:</p>
<p><img src="images/Chapter7/scrollview_settings.png" alt="image" /></p></li>
</ol>
<p>Let’s discuss the scroll view settings briefly. The most important property is the <em>Content node</em> property. Here you can choose a <span>CCB File</span> that will be displayed inside of the scroll view. We choose the <span>GameModeSelectLayer.cbb</span> that we just created. We check <em>Horizontal scroll enabled</em> because the user shall only be able to scroll left and right, not up or down. We discussed the option <em>paging enabled</em> briefly at the beginning of this section. With this setting activated the scroll view will always snap to one of the game modes and will not allow the user to stop scrolling in the middle of two game modes.</p>
<p>Great! At this point the set up of our start scene is almost complete.</p>
<h3 id="finishing-up-the-game-mode-selection-scene">Finishing up the Game Mode Selection Scene</h3>
<p>As a last step we will implement the actual selection of one of the two game modes. So far we have a scroll view that will allow users to switch between the game modes but we don’t have a mechanism to select one of the two and start a game.</p>
<p>We will add a <em>start</em> button to <em>StartScene.ccb</em> that will allow users to confirm a selected game mode and start the game. Once we have the button set up we will add an animated transition from this game mode selection screen to the gameplay scene. That transition will be triggered as soon as the player taps the start button.</p>
<p>Let’s start by adding a plain button. It is going to be positioned towards the bottom of the screen, below the label that shows the selected game mode.</p>
<p>Add a start button to the game mode selection scene:</p>
<ol>
<li><p>Open <em>StartScene.ccb</em></p></li>
<li><p>Drag a <em>Button</em> from the node library to the stage, make sure it is below the <em>background</em> node, just as the scroll view we added earlier</p></li>
<li><p>Set the <em>Position Reference Corner</em> to <em>Bottom-left</em></p></li>
<li><p>Set the <em>Position Type</em> for <em>X</em> to <em>Percent of parent container</em></p></li>
<li><p>Set the <em>X Position</em> to <em>50</em> to center the node</p></li>
<li><p>Set the <em>Y Position</em> to <em>80</em></p></li>
<li><p>Set the <em>Preferred size</em> to <em>100.0, 40.0</em></p></li>
<li><p>Set the <em>Title</em> to <em>Start!</em></p></li>
<li><p>Set the <em>Font name</em> to <em>Optima-Bold</em></p></li>
<li><p>Set the <em>Font size</em> to <em>17.00</em></p></li>
</ol>
<p>Let’s discuss some of the properties we just set up. As a short reminder - in almost all cases we want to position UI elements relative to the screen corner which they are closest to. This will result in the best behavior when the game runs on different screen sizes. Therefore we choose the <em>Bottom-Left</em> corner as reference corner (technically we could also choose the <em>Bottom-Right</em>, since we are centering the button horizontally this wouldn’t make any difference).</p>
<p>Another interesting property is the <em>Preferred Size</em>. Buttons automatically resize to be large enough to enclose their content (in this case the button text). If we want a button to appear larger than necessary we can set the <em>Preferred Size</em> property. In this example we make the button a little bit larger than is required to fit the text <em>Start!</em>.</p>
<p>We also need to set up some code connections. When the user taps the button we want to start the transition. And there’s another little feature that’s important. We only want to activate the <em>Start!</em> button when the user has selected one of the two game modes. If the user is currently scrolling between two screen modes it shouldn’t be possible to start the game. Otherwise it could be pretty unclear to the user which game mode has been selected. We’re going to solve this issue by deactivating the button when a user is scrolling between game modes.</p>
<p>Select the <em>Start!</em> button and open the <em>Code Connections</em> tab. Set up a code connection with the <em>Doc root var</em> and call it <em>playButton</em>.</p>
<p>We are going to use this code connection to activate and deactivate the start button. Towards the beginning of this book we have discussed how we can connect method calls to button taps ([target<sub>s</sub>elector]). Now we are going to use this functionality for the start button.</p>
<p>Set the <em>selector</em> (method name) to <em>playButtonPressed</em> and choose the <em>target</em> to be <em>Document root</em>.</p>
<p>As soon as the button is tapped the <span>playButtonPressed</span> method will be called on the class of the root node. Right now the root node has no class set up. Let’s change that.</p>
<p>Select the root node (top most node in the timeline) of <em>StartScene.ccb</em>, then open the code connections tab. Inside of the code connections tab set the <em>Custom class</em> to <em>StartScene</em>.</p>
<p>We’ll need one more code connection for this scene - a connection for the scroll view. Later, when we add some code to this scene you will see that we need to connect to the scroll view to get informed when it starts and stops scrolling. Whenever that happens we need to deactivate and activate the start button accordingly.</p>
<p>Select the scroll view from the timeline and open the code connection tab. Set up a code connection to <em>Doc root var</em> and name that connection <em>scrollView</em>.</p>
<p>Now we have all the code connections set up. Before we add some code to make this scene work we will work through one last step in SpriteBuilder. We’ll create a nicely animated transition from the selection scene to the gameplay scene.</p>
<h3 id="adding-a-fancy-transition-animation">Adding a Fancy Transition Animation</h3>
<p>Our transition will consist of two different components:</p>
<ol>
<li><p>The UI elements will move off the screen</p></li>
<li><p>The background image will brighten up to full opacity</p></li>
</ol>
<p>Once these two steps are complete, the gameplay action will start.</p>
<p>Here’s an illustration of what our transition will look like:</p>
<div class="figure">
<img src="images/Chapter7/gameplay_transition.png" alt="By moving UI elements out of the screen and brightening the scene up we transition from the start scene to the gameplay scene" />
<p class="caption">By moving UI elements out of the screen and brightening the scene up we transition from the start scene to the gameplay scene</p>
</div>
<p>This transition is a nice example of how menus can be integrated into games seamlessly. Using SpriteBuilder’s timeline, creating this animation is pretty straightforward. There are a bunch of steps involved, but none of them are complicated.</p>
<p>First, we’ll need to create a new timeline. The default timeline runs automatically as soon as the scene becomes visible. The animation we are about to build, in contrast, shall only run when the user has selected a game mode. Therefore we need to create new timeline which we can explicitly start playing from code.</p>
<p>Create a new timeline for our transition animation:</p>
<p><img src="images/Chapter7/new_timeline.png" alt="image" /></p>
<p>Next, rename the timeline. You can access the timeline editor through <span>SpriteBuilder</span>’s menu (<em>Animation -&gt; Edit Timelines…</em>). Change the timeline name to <em>StartGameplay</em>.</p>
<p>We want the transition to be pretty fast, so let’s set the timeline duration to 1 second.</p>
<ol>
<li><p>Switch to the <em>StartGameplay</em> timeline:</p>
<p><img src="images/Chapter7/switch_timeline.png" alt="image" /></p></li>
<li><p>Set timeline duration to 1s. If you forgot how to change the timeline duration you can skim back a few pages to figure [fig: timeline<sub>d</sub>uration]</p></li>
</ol>
<p>Next, we are going to set up keyframes for all of the UI elements that we want to move off the screen. Additionally we will fade in the background sprite. Make sure to follow the instructions exactly!</p>
<ol>
<li><p>Select the <em>background</em> sprite</p></li>
<li><p>Create an <em>Opacity Keyframe</em> at 0 seconds and set the opacity value to <em>0.7</em></p></li>
<li><p>Create a second <em>Opacity Keyframe</em> at 1 second and set the opacity to <em>1.0</em></p></li>
<li><p>Select the <em>CCButton</em></p></li>
<li><p>Create a <em>Position Keyframe</em> at 0 seconds, leave the position unchanged</p></li>
<li><p>Create a second <em>Position Keyframe</em> at 1 second and set the position to <em>(50, -400)</em></p></li>
<li><p>Select the <em>CCScrollView</em></p></li>
<li><p>Create a <em>Position Keyframe</em> at 0 seconds, leave the position unchanged</p></li>
<li><p>Create a second <em>Position Keyframe</em> at 1 second and set the position to <em>(0, -400)</em></p></li>
<li><p>Select the <em>CCLabelTTF</em></p></li>
<li><p>Create a <em>Position Keyframe</em> at 0 seconds, leave the position unchanged</p></li>
<li><p>Create a second <em>Position Keyframe</em> at 1 second and set the position to <em>(50, -50)</em></p></li>
</ol>
<p>Great! If you want you can test the animation with the <span>SpriteBuilder</span> timeline playback feature.</p>
<p>There’s one last step left in <span>SpriteBuilder</span> before we move to <span>Xcode</span> and implement the actual transition between start scene and gameplay. As soon as the animation completes, that means all UI elements have moved off the screen and the background is brightened up completely, we want to switch to the gameplay scene. Switching scenes has to be implemented in code. This means that we need a callback in code that gets triggered as soon as this animation completes.</p>
<p><span>SpriteBuilder</span> and <span>Cocos2D</span> provide three different ways to implement this:</p>
<ul>
<li><p>Provide a completion block to the animation manager of a scene. This completion block will be called whenever a timeline animation completes</p></li>
<li><p>Implement a delegate method that gets called by the animation manager when a timeline animation completes</p></li>
<li><p>Set up a callback method within a <span>SpriteBuilder</span> timeline animation</p></li>
</ul>
<p>For this section I want to go with the last option. The ability to call methods as part of timeline animations can be useful in many situations, so I want to use it as early as possible!</p>
<p>To add a callback method to a timeline animation you need to <em>Option-Key + Click</em> into the <em>Callbacks</em> line of the timeline editor:</p>
<p><img src="images/Chapter7/timeline_callback.png" alt="image" /></p>
<p>Place that callback at 1 second. You can also choose the <em>target</em> and <em>selector</em> for this callback. Select <em>Document root</em> as target and <em>transitionAnimationComplete</em> as selector.</p>
<p>Great! This was quite a lot of work, but now we have a game mode selection scene (including a scroll view) and a great transition into the gameplay scene. Now it’s time to switch back to code!</p>
<h3 id="implementing-the-game-mode-selection">Implementing the Game Mode Selection</h3>
<p>Publish the <span>SpriteBuilder</span> project and switch to the <span>Xcode</span> project.</p>
<p>The first change we need to make to the <span>Xcode</span> project is to set up which scene gets presented when our game starts. By default it’s the <em>MainScene</em>. However, we have created a new <em>StartScene</em> and want that one to be the first scene of the game.</p>
<p>We can change this setting in the <em>AppDelegate</em> of the project.</p>
<p>Open <em>AppDelegate.m</em> in <em>Source/Platforms/iOS/</em>:</p>
<p><img src="images/Chapter7/app_delegate.png" alt="image" /></p>
<p>The <span>AppDelegate</span> of <span>Cocos2D</span> is written in Objective-C. If you don’t know Objective-C, don’t worry, the change we need to make is trivial.</p>
<p>When a <span>Cocos2D</span> game starts, the <span>startScene</span> method of the <span>AppDelegate</span> gets called. That method is responsible for loading and returning the start scene of the game. Let’s modify it to load <span>StartScene</span> instead of <span>MainScene</span>.</p>
<p>Modify the <span>startScene</span> method of <em>AppDelegate.m</em> to look as following:</p>
<pre><code>- (CCScene*) startScene
{
    return [CCBReader loadAsScene:@&quot;StartScene&quot;];
}</code></pre>
<p>Great! Now our new start scene will be presented when our game starts. Note that the game won’t run at this point. We need to create the <span>StartScene</span> class. We’re already referencing this class from the <span>SpriteBuilder</span> project, but we haven’t created it yet.</p>
<p>Create a new Swift file. Call it <span>StartScene</span>. Set up the basic <span>StartScene</span> class like this:</p>
<pre><code>class StartScene: CCNode {
  
  weak var scrollView: CCScrollView!
  weak var playButton: CCButton!
  var selectedGameMode: MainScene.GameModeSelection = .Endless
  
}</code></pre>
<p>The first two variables are necessary for the code connections that we set up in our <span>SpriteBuilder</span> project. The third variable stores which game mode the player has currently selected. Since the game mode is a choice between multiple options an enum is a great way to model this. The enum referenced here (<span>MainScene.GameModeSelection</span>) does not exist yet. We need to add it to the <span>MainScene</span> class.</p>
<p>Open <em>MainScene.swift</em> and add the following lines:</p>
<pre><code>var selectedGameMode: GameModeSelection?
  
enum GameModeSelection: Int {
  case Endless
  case Timed
}</code></pre>
<p>The first line is a property that stores the game mode of the current game. Later we will use that property to apply different rules to the gameplay and display different score information based on the game mode that player picker. The information on which game mode the player has picker will be handed to us by the <span>StartScene</span>.</p>
<p>We’ve also added an enum definition. The <span>GameModeSelection</span> enum has two different states, one for each game mode. For now we will only implement an endless and a timed game mode. As we’ve done earlier, we are associating <em>raw values</em> with this enum by adding the <span>Int</span> type after the enum name. This means that the <span>Endless</span> value corresponds to 0 and the <span>Timed</span> value corresponds to 1.</p>
<p>Now we can switch back to working on our new start scene. There are three features we need to implement in <em>StartScene.swift</em>. We need to keep track of the movement of the scroll view. When the user scrolls to one of the two pages of the scroll view, we need to remember which game mode has been chosen. Further, as discussed earlier, we need to deactivate the <em>Start!</em> button while the user scrolls. Finally, we need to trigger a transition to the gameplay scene (<span>MainScene</span>) as soon as a user taps the start button. As part of that transition we need to inform <span>MainScene</span> which game mode was selected. Let’s start with the scroll view related code.</p>
<h4 id="implementing-a-scroll-view-delegate">Implementing a Scroll View Delegate</h4>
<p>If you have written code for the iOS platform before, you are very familiar with the principle of delegation. However, this book does not necessarily require previous iOS app development knowledge.</p>
<p>If you haven’t heard of delegation before, Apple has a great introduction in their developer guide: <a href="https://developer.apple.com/library/ios/documentation/General/Conceptual/DevPedia-CocoaCore/Delegation.html" class="uri">https://developer.apple.com/library/ios/documentation/General/Conceptual/DevPedia-CocoaCore/Delegation.html</a>.</p>
<p>The <span>CCScrollView</span> in <span>Cocos2D</span> also uses the delegate pattern. This is what the (Objective-C) protocol looks like:</p>
<pre><code>@protocol CCScrollViewDelegate &lt;NSObject&gt;

@optional
- (void)scrollViewDidScroll:(CCScrollView *)scrollView;
- (void)scrollViewWillBeginDragging:(CCScrollView *)scrollView;
- (void)scrollViewDidEndDragging:(CCScrollView * )scrollView willDecelerate:(BOOL)decelerate;
- (void)scrollViewWillBeginDecelerating:(CCScrollView *)scrollView;
- (void)scrollViewDidEndDecelerating:(CCScrollView *)scrollView;

@end</code></pre>
<p>There are a total of five methods that we can implement. The <span>optional</span> keyword marks a section of the protocol in which all listed methods are not required to be implemented. In this specific protocol <em>all</em> methods are optional.</p>
<p>We want to be informed when the scroll view starts and ends scrolling. There are two methods that get called in these cases: <span>scrollViewWillBeginDragging</span> and <span>scrollViewDidEndDecelerating</span>. Let’s become the delegate of our scroll view and implement these methods.</p>
<p>The first step is setting ourselves up as the delegate of the scroll view. We can set ourselves as the delegate as soon as the scene is entirely loaded (when <span>didLoadFromCCB</span> is called).</p>
<p>Add the following implementation of <span>didLoadFromCCB</span> to <span>StartScene</span>:</p>
<pre><code>func didLoadFromCCB() {
  scrollView.delegate = self
}</code></pre>
<p>Now the scroll view knows about us and will call all the methods of the <span>CCScrollViewDelegate</span> protocol that we implement.</p>
<p>Next, we need to add the protocol implementation. In Swift it is common to implement protocols in class extensions. Class extensions allow us to add functionality to a class outside of its original definition. Moving all protocol implementations into separate class extensions is a nice way of keeping our code organized.</p>
<p>The implementation of our two protocol methods is pretty simple. When the user starts scrolling we deactivate the start button. When the user ends scrolling, we activate the start button and remember the selected game mode.</p>
<p>Add the following protocol implementation to <span>StartScene.swift</span>. It is <strong>important</strong> that the class extension is <strong>not</strong> part of the class, but placed after the closing curly brackets of the class definition:</p>
<pre><code>class StartScene: CCNode {
  ...  
}

extension StartScene: CCScrollViewDelegate {
  
  func scrollViewWillBeginDragging(scrollView: CCScrollView) {
    playButton.enabled = false
  }
  
  func scrollViewDidEndDecelerating(scrollView: CCScrollView) {
    playButton.enabled = true
    selectedGameMode = MainScene.GameModeSelection(rawValue: Int(scrollView.horizontalPage))!
  }
  
}</code></pre>
<p>Activating and deactivating the button is very simple; <span>CCButton</span> provides a property for it. Choosing the game mode based on the selected scroll view page is similarly straightforward. <span>CCScrollView</span> provides a <span>horizontalPage</span> property that allows use to read which page the user has currently scrolled to. We use that value to select the according game mode. In order to create an enum value from a number we need to use the <span>rawValue:</span> initializer (remember that 0 corresponds to the endless game mode and 1 to the timed game mode).</p>
<p>Our work with the scroll view is completed. Next, let’s implement the callback method for the button interaction. As soon as the play button is tapped we want to play the transition animation that we created in <span>SpriteBuilder</span>. Additionally, we should deactivate the scroll view. That way users cannot modify the selected game mode while the scene is in transition.</p>
<p>Implement the <span>playButtonPressed</span> method that we’ve set up in <span>SpriteBuilder</span> inside of <span>StartScene</span>. This should be implemented as part of the core class, not of the extension:</p>
<pre><code>  func playButtonPressed() {
    scrollView.userInteractionEnabled = false
    animationManager.runAnimationsForSequenceNamed(&quot;StartGameplay&quot;)
  }</code></pre>
<p>First, we deactivate user interaction on the scroll view. Whichever game mode has been selected by the user before hitting the play button will stay selected throughout the animation. Then we run the actual animation. Remember that all timelines created in <span>SpriteBuilder</span> can be referenced in code by using their name.</p>
<p>Now there’s a last method left to be implemented. We have added a callback to the timeline animation that gets called when the transition animation is completed. In the implementation of that method we should perform the actual scene transition, which means replacing the <span>StartScene</span> with the <span>MainScene</span>. The animation that we are running only moves the UI elements off the screen. However, as you might remember transition between scenes can only be implemented in code.</p>
<p>Transitions between scenes can also be animated. For the transition from the start scene to the gameplay scene we will use a cross fade transition. Add the end of our timeline animation the start scene is entirely empty. Then we use a cross fade animation to transition to the gameplay scene where the pot will be displayed. The cross fade animation will make the pot appear slowly before the actual game starts.</p>
<p>Add the following implementation for the timeline callback, that we’ve set up in <span>SpriteBuilder</span>, to <span>MainScene</span>:</p>
<pre><code>func transitionAnimationComplete() {
  let scene = CCBReader.loadAsScene(&quot;MainScene&quot;)
  let gameplay = scene.children[0] as! MainScene
  gameplay.selectedGameMode = selectedGameMode
  let transition = CCTransition(crossFadeWithDuration: 0.7)
  CCDirector.sharedDirector().replaceScene(scene, withTransition: transition)
}</code></pre>
<p>This method gets called as soon as the transition animation ends. Within it we perform some scene transition code with which you should be familiar from our very first <span>SpriteBuilder</span> project. That code hides the <span>StartScene</span> and presents the <span>MainScene</span>.</p>
<p>Great! Now our game mode selection screen is complete; including an awesome transition to the gameplay scene. You can run the project and try it out.</p>
<p>The next big step for our project is implementing the two different game modes. While implementing the game modes you will learn how to build modular and extensible code!</p>
<p>We will start off by creating two different UIs for the two game modes.</p>
<p>In the endless game mode the player will loose health for dropping items or collecting incorrect items and will gain health for collecting correct items. For the endless mode we need to display a health bar.</p>
<p>In the timed mode the player will have a hard time limit. For that mode we need to display a counter that shows the remaining time and a score label.</p>
<h2 id="implementing-multiple-game-modes">Implementing Multiple Game Modes</h2>
<p>Let’s get started on building the two different game modes.</p>
<p>We’re going to start with setting up the UI in for each game mode in <span>SpriteBuilder</span>. Then we will come up with a way to implement the two game modes without duplicating code - this is a great use case for exploring some potential design patterns for game development.</p>
<h3 id="adding-uis-for-different-game-modes">Adding UIs for Different Game Modes</h3>
<p>Open your <span>SpriteBuilder</span> project. We’re going to create two separate <span>CCB File</span>s, one for the UI elements of each game mode.</p>
<h4 id="ui-for-the-timed-game-mode">UI for the Timed Game Mode</h4>
<ol>
<li><p>Create a new <span>CCB File</span> of type <em>Layer</em> and name it <em>TimedModeUI</em></p></li>
<li><p>Select the root node of the new <span>CCB File</span> and change the <em>Content size type</em> to be <em>percentage of parent container</em> for both, width and height</p></li>
<li><p>Set the <em>Content Size</em> to <em>(100, 100)</em></p></li>
</ol>
<p>We will place all UI elements relative to the edges of the screen. That way the UI will look good on any given screen size. That’s why we want the root node to take 100% the size of its parent container. If we instead would use a fixed size for this layer our UI would not respond to multiple screen sizes.</p>
<p>The UI for the timed game mode is not too complicated, it consists of two separate labels. We want the style of these labels to be consistent with the labels that we used on the start scene. The easiest way to do accomplish this is to actually copy the label in <span>SpriteBuilder</span>.</p>
<ol>
<li><p>Open <span>StartScene.ccb</span></p></li>
<li><p>Select the <em>CCLabelTTF</em> from the timeline</p></li>
<li><p>Now select <em>Edit -&gt; Copy</em> from the <span>SpriteBuilder</span> menu (or use the shortkey: <em>CMD+C</em>)</p></li>
<li><p>Next, open <span>TimedModeUI.ccb</span></p></li>
<li><p>Select <em>Edit -&gt; Paste</em> from the <span>SpriteBuilder</span> menu (or use: <em>CMD+V</em>).</p></li>
</ol>
<p>Now you should have an exact copy of the start scene label in your new <span>CCB File</span>. We’ll make a small tweak to this label and lay it out correctly.</p>
<p>Apply the following changes to the label:</p>
<ol>
<li><p>Select the <em>Position Reference Corner</em> to be the top left corner</p></li>
<li><p>Change the <em>Position Type</em> for <em>X</em> to be <em>in Points</em></p></li>
<li><p>Change the position to <em>(20,20)</em></p></li>
<li><p>Change the anchor point to <em>(0.0, 1.0)</em></p></li>
<li><p>Change the label text to <em>Time: 0</em></p></li>
<li><p>Change the font size to <em>30</em></p></li>
<li><p>Set up a code connection to the <strong>Owner var</strong> (not the <em>Doc root var</em>; this is very important!) and name it <em>timeLabel</em></p></li>
</ol>
<p>Now the label should be nicely positioned in the top left corner!</p>
<p>This is the first time we are using a variable which is assigend to the <strong>Owner var</strong>. We will not be creating a custom class for this <span>CCB File</span>, since it doesn’t have any specific behavior that we need to implement.</p>
<p>Instead we will later assign the code connections to the classes that contain the actual gameplay logic. The <span>MainScene</span> instance will become the owner of this <span>CCB File</span> which means it will have access to all <em>Owner vars</em>.</p>
<p>That’s why it’s important to set up the code connection with the <em>Owner var</em> instead of the <em>Doc root var</em>.</p>
<p>Next, let’s create the points label. Since it will look almost identical to the time label we should save some time and just copy and modify the label again instead of starting with a new label from scratch. Note however, that you should be careful when using this approach. When you copy a node all of its properties are copied along with it (including code connections). If you aren’t careful you might end up with hard to debug issues (e.g two nodes attempt to use the same code connection variable).</p>
<p>Copy the time label that you just created it and paste it. Change the pasted label as following:</p>
<ol>
<li><p>Select the <em>Position Reference Corner</em> to be the top right corner</p></li>
<li><p>Change the <em>Anchor point</em> to <em>(1.0, 1.0)</em></p></li>
<li><p>Change the <em>label text</em> to <em>Points: 0</em></p></li>
<li><p>Set the <em>Position</em> to <em>(20, 20)</em></p></li>
<li><p>Set up a code connection to the <strong>Owner var</strong> and name it <em>pointsLabel</em></p></li>
</ol>
<p>Great! The UI for the timed game mode is completed. It should look as following:</p>
<p><img src="images/Chapter7/timed_mode_ui.png" alt="image" /></p>
<h4 id="ui-for-the-endless-game-mode">UI for the Endless Game Mode</h4>
<p>Now, let’s create the UI for the endless game mode which will contain a health bar. We’ll start of by creating a new <span>CCB File</span>.</p>
<p>Set up the <span>CCB File</span> for the endless game mode UI:</p>
<ol>
<li><p>Create a new <span>CCB File</span> of type <em>Layer</em> and name it <em>EndlessModeUI</em></p></li>
<li><p>Select the root node of the new <span>CCB File</span> and change the <em>Content size type</em> to be <em>Percent of parent container</em> for both, width and height</p></li>
<li><p>Set the <em>Content Size</em> to <em>(100, 100)</em></p></li>
</ol>
<p>Next, let’s add a label that displays the amount of seconds a player has survived. Once again we can copy the existing label from the <span>TimeModeUI.ccb</span> file since we want both labels to look identical.</p>
<p>Open <span>TimeModeUI.ccb</span> and copy the label in the <strong>top left corner</strong>. Then open <span>EndlessModeUI.ccb</span> and paste the label. Select the pasted label and modify it as following:</p>
<ol>
<li><p>Change the label text to <em>Survived: 0</em></p></li>
<li><p>Set up a code connection to the <strong>Owner var</strong> and name it <em>survivedLabel</em></p></li>
</ol>
<p>Besides this label we will also need to display a health bar in the endless game mode. The easiest way to implement a health bar in <span>Cocos2D</span> is taking a plain <span>CCColorNode</span> and scaling it depending on the current health level of the player.</p>
<p>Add the health bar to <em>EndlessModeUI.ccb</em>:</p>
<ol>
<li><p>Drag a <em>Color Node</em> from the node library to the stage</p></li>
<li><p>Select the <em>Position Reference Corner</em> to be the <em>top right corner</em></p></li>
<li><p>Change the <em>Position</em> to <em>(20,20)</em></p></li>
<li><p>Change the <em>Anchor point</em> to <em>(1.0, 1.0)</em></p></li>
<li><p>Chante the <em>Content size</em> to <em>(150, 40)</em></p></li>
<li><p>Change the node color to <em>green</em> (or pick any other color you enjoy)</p></li>
<li><p>Set up a code connection to the <strong>Owner var</strong> and name it <em>healthBar</em></p></li>
</ol>
<p>Now the UI for the endless mode should look like this:</p>
<p><img src="images/Chapter7/endless_mode_ui.png" alt="image" /></p>
<p>We’re done with the UI setup. To make these score displays actually show up as part of the game, we’ll now move to implementing the two game modes!</p>
<h3 id="implement-game-logic-for-different-modes">Implement Game Logic for Different Modes</h3>
<p>We need to change multiple parts of our game to support two different game modes. Depending on which game mode a player selects, we want to display a different score board and also implement a different set of rules.</p>
<p>We want to implement a design that allows us to add many more game modes in future - without convoluting the code base.</p>
<p>Before we dive into coding, let’s try to figure out what we’ll need to implement:</p>
<ul>
<li><p>When we start a game, the <span>MainScene</span> class needs to know which game mode a user has selected</p></li>
<li><p><span>MainScene</span> shouldn’t know anything about the rules of the selected game mode. That way we could create additional game modes in future without increasing the complexity of <span>MainScene</span></p></li>
<li><p>Every game mode should know about its rules (when does a player earn / loose points, when does a game end)</p></li>
<li><p>Every game mode should know which score board entries it has and it should be responsible for updating them based on the current state of the game</p></li>
</ul>
<p>We should try to come up with a solution that lets us add more game modes as easily as possible. One modular way of implementing this is setting up different game modes as individual classes. These classes can be referenced by the <span>MainScene</span> class. In this scenario, the <span>MainScene</span> class remains responsible for the core of the game, it spawns falling objects (though, even this could be moved into the gameplay classes eventually) and lets them fall to the ground. It handles collision detection and determines if an object was caught or dropped.</p>
<p>The consequences of catching or dropping objects however, are not implemented in the <span>Gameplay</span> class itself. Instead, they are implemented by the game modes. This means that the <span>Gameplay</span> class needs to inform the game mode when a significant event occurs. The game mode itself can then decide how this event impacts the gameplay.</p>
<p>Here’s a diagram that illustrates our solution:</p>
<p><img src="images/Chapter7/gameplay_design.png" alt="image" /></p>
<p>We’ll create a <span>GameMode</span> protocol that defines the communication between <span>MainScene</span> and the different game modes. Each game mode will implement the <span>GameMode</span> protocol.</p>
<h4 id="defining-a-protocol-for-game-modes">Defining a Protocol for Game Modes</h4>
<p>Let’s start implementing this design. The first step is defining a protocol that can be implemented by all game modes. In the diagram above I’ve highlighted the protocol in green.</p>
<p>As discussed, there are three events that we are interested in; all of them should be part of our protocol.</p>
<p>Create a new Swift file in <span>Xcode</span> and call it <span>GameMode.swift</span>. Then add the following protocol definition to it:</p>
<pre><code>typealias GameOver = Bool

protocol GameMode: class {
  var userInterface: CCNode! { get }

  func gameplay(mainScene:MainScene, droppedFallingObject:FallingObject)
  func gameplay(mainScene:MainScene, caughtFallingObject:FallingObject)
  func gameplayStep(mainScene:MainScene, delta: CCTime) -&gt; GameOver
}</code></pre>
<p>Note that I have omitted the source code documentation of this protocol for the sake of brevity.</p>
<p>The protocol we’ve just defined will be implemented by multiple classes, it’s important to document its methods and properties for developers that want to add game modes in future. You can take a look at the source code for this protocol on GitHub (<a href="https://github.com/SpriteBuilder-Book/Code/blob/master/Chapter7/FallingObjects.spritebuilder/GameMode.swift" class="uri">https://github.com/SpriteBuilder-Book/Code/blob/master/Chapter7/FallingObjects.spritebuilder/GameMode.swift</a>) to read the documentation.</p>
<p>[Source code documentation in Swift] Many details about source code documentation in Swift are still up in the air. NSHipster provides a great article that describes the currently supported documentation style: <a href="http://nshipster.com/swift-documentation/" class="uri">http://nshipster.com/swift-documentation/</a>.</p>
<p>Let’s discuss this protocol in detail. The first interesting aspect is a <span>typealias</span> statement before the protocol declaration. The <span>typealias</span> keyword in Swift allows us to give a type a new alias name. In this case we are creating a new type called <span>GameOver</span> which is actually just a <em>Bool</em>. Using <span>typealias</span> is a nice way of better capturing the semantics of a type. A method that returns a type of <span>GameOver</span> is easier to understand than a method returning a plain <span>Bool</span>.</p>
<p>The second thing to note is that we have defined the protocol as a <em>class-only</em> protocol. We can do that by adding the <span>class</span> keyword to the protocol’s inheritance list. Later you’ll see that any type that implements <span>GameMode</span> is required to be a reference type, because we need to pass references to it to the <span>Cocos2D</span> framework.</p>
<p>We start our protocol by defining a property: <span>userInterface</span>. This property shall provide access to the game mode’s user interface. The <span>MainScene</span> class can use this property to access the UI for the currently active game mode. We only expose as a getter as part of the protocol, the UI cannot be assigned from outside of the game mode class. Each game mode creates its own UI and is responsible for holding on to it.</p>
<p>Next, we define two methods that get called when objects get dropped or caught. Both methods receive a reference to the <span>MainScene</span>. This is pretty common when using the delegate pattern. Theoretically a game mode instance could be the delegate of multiple <span>MainScene</span> instances. By passing the <span>MainScene</span> in which the event occurred to the delegate the delegate gets the chance to respond differently depending which instance has called the method. It’s good to conform to that convention - however we won’t sign up as the delegate of multiple <span>MainScene</span> instances.</p>
<p>The second parameter sent to both methods is the object which has been caught or dropped. The class implementing the <span>GameMode</span> can use this information to determine whether points should be added or subtracted.</p>
<p>The last method(<span>gameplayStep:</span>) fulfills two purposes. Firstly, it allows game modes to hook into the update method of <span>MainScene</span>. That is necessary for any time based actions, e.g. capturing the total time that has passed since the beginning of the game. The second purpose is fulfilled by the <span>GameOver</span> return value. The return value allows the game mode to tell the <span>MainScene</span> that the game is over. All game modes will use this method to implement the game over condition.</p>
<p>Now that our protocol is defined we can implement the two game modes.</p>
<h4 id="implementing-the-timed-game-mode">Implementing the Timed Game Mode</h4>
<p>Let’s start by implementing the timed game mode. Since we thought about the software design upfront and even defined a protocol for game modes, the implementation itself is not too complicated.</p>
<p>Create a new Swift file and name it <span>TimedGameMode</span>. Add the following class definition to the new file:</p>
<pre><code>@objc(TimedGameMode)
class TimedGameMode: GameMode {
  var timeLabel: CCLabelTTF!
  var pointsLabel: CCLabelTTF!
}</code></pre>
<p>There’s a lot going on in these few lines. Firstly, we need the <span>@objc</span> annotation to make this class visible to <span>Cocos2D</span>. <span>Cocos2D</span> is written in Objective-C and can only see classes that are subclasses of <span>NSObject</span> or that have the <span>@objc</span> annotation. So far all of our classes have been subclasses of <span>Cocos2D</span> classes, and all of them in turn are derived from <span>NSObject</span>, therefore this annotation wasn’t necessary. The <span>TimedGameMode</span> class is our first class that is not a subclass of an Objective-C class.</p>
<p>In the second line we declare that our class conforms to the <span>GameMode</span> protocol. We also declare two properties for the code connections that we set up in the <span>CCB File</span> for the timed game mode. We have access to two different labels, one displays the player’s points the other one displays the time that’s left.</p>
<p>We’ll need a whole set of additional variables. We need a <span>userInterface</span> variable to conform to the <span>GameMode</span> protocol. We also need variables to store the amount of points the player has scored and the time that is left in the current game.</p>
<p>Add the following properties and property observers to the <span>TimedGameMode</span> class:</p>
<pre><code>let minPoints = 0
let minTime = 0.0

private(set) var userInterface: CCNode!

private var time: CCTime = 10 {
  didSet {
    updateTimeDisplay(time)
  }
}

private var points: Int = 0 {
  didSet {
    updatePointsDisplay(points)
  }
}</code></pre>
<p>The first two constants are used to define the bottom line for time and points in this game mode. In almost all cases using constants should be preferred over using number literals directly in code. By defining constants our intentions are obvious to other developers and we can update the values in one place.</p>
<p>Further, we add the <span>userInterface</span> variable. This variable will store the loaded <span>CCB File</span> that belongs to the timed game mode. It is also required to conform with the <span>GameMode</span> protocol.</p>
<p>Next, we declare and define the <span>time</span> property that stores the time that is left during the current game. For testing purposes our games only last 10 seconds. We also add a property observer. When the time value changes we call the (yet to be implemented) <span>updateTimeDisplay:</span> method, that method updates the label that displays the leftover time.</p>
<p>We essentially do the same for the <span>points</span> property.</p>
<p>Next, let’s implement the two helper methods that update the time and point labels.</p>
<p>Add the following two methods to <span>TimedGameMode</span>:</p>
<pre><code>func updatePointsDisplay(points: Int) {
  pointsLabel.string = &quot;Points: \(points)&quot;
}

func updateTimeDisplay(time: CCTime) {
  timeLabel.string = &quot;Time: \(Int(time))&quot;
}</code></pre>
<p>These methods are very simple. We only warp this code into separate methods because we need the functionality in multiple places, as you’ll see shortly.</p>
<p>Next, before we implement the methods defined in our protocol, let’s tackle the initializer of this class. The main task the initializer needs to perform is loading the game mode’s UI from a <span>CCB File</span>.</p>
<p>Add the following initializer:</p>
<pre><code>init() {
  userInterface = CCBReader.load(&quot;TimedModeUI&quot;, owner:self)
  updatePointsDisplay(points)
  updateTimeDisplay(time)
}</code></pre>
<p>In the first line we load the <span>TimedModeUI</span> <span>CCB File</span>. We store the loaded node hierarchy in the <span>userInterface</span> property, that way it can be accessed by <span>MainScene</span>. We also call our two label helper methods, so that the labels display the correct initial values for time and points.</p>
<p>Now we can move on to the core of this class: the methods that are required by the <span>GameMode</span> protocol.</p>
<p>Let’s start with the <span>gameplay(mainScene:, droppedFallingObject:)</span> method. At this point it’s time to make some decisions on the rules of the timed game mode.</p>
<p>I suggest that we subtract 1 point when the player drops an object that should be caught. Because we don’t want to be too mean we set the lowest possible score to 0.</p>
<p>Add the following method to <span>TimedGameMode</span>:</p>
<pre><code>func gameplay(mainScene:MainScene, droppedFallingObject:FallingObject) {
  if (droppedFallingObject.type == .Good) {
    points = max(points - 1, minPoints)
  }
}</code></pre>
<p>If the object that has been dropped is a <span>.Good</span> object, we subtract one point. Using Swift’s <span>max</span> function we make sure that the total score never drops below <span>minPoints</span>, which we have defined as 0.</p>
<p>If a <span>.Bad</span> object drops the score is not influenced. Therefore we don’t need to cover this case here.</p>
<p>Next, we’ll implement the method that gets called when objects are caught. Once again time to decide on some rules. I propose to add a point when a good object is caught and subtract a point when a bad object is caught. You can obviously feel free to use different values!</p>
<p>Add the method for caught objects to <span>TimedGameMode</span>:</p>
<pre><code>func gameplay(mainScene:MainScene, caughtFallingObject:FallingObject) {
  switch (caughtFallingObject.type) {
  case .Bad:
    points = max(points - 1, minPoints)
  case .Good:
    points += 1
  }
}</code></pre>
<p>Since we are checking for multiple possible values of an enum using a switch statement results in nicely readable code. Besides the switch statement the implementation is pretty straightforward.</p>
<p>Now there’s only one last method to implement: <span>gameplayStep(mainScene:, delta:)</span> We need to do two things in the implementation of this method:</p>
<ol>
<li><p>Subtract the passed time (<span>delta</span>) from the remaining game time</p></li>
<li><p>Check if the remaining time reached the minimum time (0.0) and return <span>true</span> if that’s the case</p></li>
</ol>
<p>Add the following implementation of the step method to <span>TimedGameMode</span>:</p>
<pre><code>func gameplayStep(mainScene: MainScene, delta: CCTime) -&gt; GameOver {
  time -= delta
  return !(time &gt; minTime)
}</code></pre>
<p>First, we subtract <span>delta</span> from the remaining game time. Next, we check if the total time is over or not and return a <span>GameOver</span> value based on that.</p>
<p>Congratulations! We have fully implemented our first game mode. Now, let’s implement the endless game mode.</p>
<h4 id="implementing-the-endless-game-mode">Implementing the Endless Game Mode</h4>
<p>The procedure for implementing the endless game mode will be very similar to the timed one: Setting up code connections, implementing game mode rules and updating the scoreboard.</p>
<p>Let’s start with setting up the basic class and code connections.</p>
<p>Create a new Swift file in <span>Xcode</span> and name it <em>EndlessGameMode</em>. Then add the following class definition and properties:</p>
<pre><code>@objc(EndlessGameMode)
class EndlessGameMode: GameMode {
  var healthBar: CCNode!
  var survivedLabel: CCLabelTTF!
}</code></pre>
<p>As I said, this is pretty similar to the timed game mode. We need the <span>@objc</span> annotation because this class does not inherit from an Objective-C class. We declare two properties for the two UI elements in the <span>EndlessModeUI</span> <span>CCB File</span>.</p>
<p>In the endless game mode we will have two game parameters that we want to keep track off: the current <em>health</em> of the player and the <em>survivalTime</em> of the current game. In the endless game mode the player has the goal of surviving as long as possible. Instead of gaining points for catching objects the player regains some health. Whenever the player catches an incorrect object or drops a good object she looses health. We’ll need properties to keep track of these values.</p>
<p>Additionally we’ll need a property that stores the UI node to conform with the <span>GameMode</span> protocol.</p>
<p>Add the following properties and property observers to <span>EndlessGameMode</span>:</p>
<pre><code>private(set) var userInterface: CCNode!
private let minHealth = 0
private let maxHealth = 10

private var health:Int = 10 {
  didSet {
    let newScale = Float(health) / Float(maxHealth)
    let scaleAction = CCActionScaleTo.actionWithDuration(0.2, scaleX: newScale,
    scaleY: 1.0) as! CCAction
    
    healthBar.stopAllActions()
    healthBar.runAction(scaleAction)
  }
}

private var survivalTime: CCTime = 0.0 {
  didSet {
    survivedLabel.string = &quot;Survived: \(Int(survivalTime))&quot;
  }
}</code></pre>
<p>We start of with a variable that stores the user interface for this game mode. Then we define two constants for the upper and lower bounds of the player’s health.</p>
<p>Next, we define the actual <span>health</span> variable and initialize it to <em>10</em>. We also add a property observer to <span>health</span>. Whenever the value changes we need to rescale the green health bar to reflect the new value. We calculate the new scale by dividing the current health by the maximum health. Instead of simply assigning new scale we apply the change as an animation. It’s these small details that make games look more polished, and in <span>Cocos2D</span> they are easy to implement. <span>Cocos2D</span> provides a scale action (<span>CCActionScaleTo</span>), we define it to run in 0.2 seconds. Before we start the action we ensure that all other actions are stopped. Since the action takes 0.2 seconds to complete it is likely that we start a new scale action while an old one is still in progress. Two actions fighting against each other would result in serious glitches, therefore it’s important to call <span>stopAllActions()</span>.</p>
<p>Finally, we add a property that stores the survival time. We once again add a property observer, in this case we update the time label whenever the survival time changes.</p>
<p>Next, we need to add the initializer that will load the user interface.</p>
<p>Add the following init method to <span>EndlessGameMode</span>:</p>
<pre><code>init() {
  userInterface = CCBReader.load(&quot;EndlessModeUI&quot;, owner:self)
}</code></pre>
<p>This code is basically analogous to the <span>TimedGameMode</span>.</p>
<p>Now all that is left is implementing the game rules as part of the three methods defined in the <span>GameMode</span> protocol.</p>
<p>When the player drops a <span>.Good</span> object, we subtract a point.</p>
<p>Add the following method to <span>EndlessGameMode</span>:</p>
<pre><code>func gameplay(mainScene:MainScene, droppedFallingObject:FallingObject) {
  if (droppedFallingObject.type == .Good) {
    health = max(health - 1, minHealth)
  }
}</code></pre>
<p>We once again use the <span>max</span> function to ensure that the health does not drop below our defined minimum.</p>
<p>Next, let’s implement the method that informs us about a caught object. When the user catches a <span>.Good</span> object he regains a health point, when he catches a <span>.Bad</span> object he looses one.</p>
<p>Add the following method to the <span>EndlessGameMode</span> class:</p>
<pre><code>func gameplay(mainScene:MainScene, caughtFallingObject:FallingObject) {
  switch (caughtFallingObject.type) {
  case .Bad:
    health = max(health - 1, minHealth)
  case .Good:
    health = min(health + 1, maxHealth)
  }
}</code></pre>
<p>The last method we need to implement is the <span>gameplayStep(mainScene:, delta:)</span> method. We need to keep track of the time that the user has survived. We can do that by adding up all the delta time frames that we receive in this method. Additionally we need to determine the game over situation. In this game mode the player loses as soon as her health drops to the minimum health.</p>
<p>Add the <span>gameplayStep(mainScene:, delta:)</span> to <span>EndlessGameMode</span>:</p>
<pre><code>func gameplayStep(mainScene: MainScene, delta: CCTime) -&gt; GameOver {
  survivalTime += delta
  return (health &lt;= minHealth)
}</code></pre>
<p>And this completes our second game mode. As you can see there weren’t too many surprises after implementing the <span>TimedGameMode</span>.</p>
<p>Before we can move on and test these two game modes, we need to integrate them into the <span>MainScene</span> class.</p>
<h3 id="connecting-the-game-modes-to-the-main-scene">Connecting the Game Modes to the Main Scene</h3>
<p>The last important step in implementing the game modes is connecting them to <span>MainScene</span>. Currently the <span>StartScene</span> passes the selected game mode to the <span>MainScene</span>. The next step for <span>MainScene</span> will be creating an instance of a game mode based on this selection.</p>
<p>Additionally we need to modify <span>MainScene</span> to call the methods defined in <span>GameMode</span> whenever objects are caught, dropped and when the <span>update</span> method is called.</p>
<p>Let’s start with instantiating one of our two game modes. In order to do that we need a variable that can store the created game mode object and a property observer for the <span>gameMode</span> property. Observing the <span>gameMode</span> property will allow us to instantiate a game mode object as soon as a game mode has been selected:</p>
<p>Add a property to store the instantiated game mode:</p>
<pre><code>var gameMode:GameMode?</code></pre>
<p>Next, replace the existing property definition for <span>selectedGameMode</span> with this property and observer definition:</p>
<pre><code>var selectedGameMode:GameModeSelection = .Endless {
  didSet {
    switch (selectedGameMode) {
    case .Endless:
      gameMode = EndlessGameMode()
    case .Timed:
      gameMode = TimedGameMode()
    }
    
    self.addChild(gameMode?.userInterface)
    gameMode?.userInterface.zOrder = DrawingOrder.ScoreBoard.rawValue
  }
}</code></pre>
<p>Swift requires all non Optional properties to have a value after the initializer of the class is called. Since <span>selectedGameMode</span> is is not initialized from the <span>init</span> method, but is instead set by an outside caller after initialization we would have to mark it as an Optional type. An alternative to that is assigning an initial value. In this case it makes sense to work with such a default value. If the outside caller does not select a specific game mode, we run the <span>.Endless</span> game mode and all of the code in <span>MainScene</span> works as expected.</p>
<p>Inside of the property observer we first switch over the potential game modes. Depending on the game mode we instantiate a different game mode class. Next, we add the user interface of the created game mode to <span>MainScene</span>. If you are fairly new to Swift you might be surprised by the question mark in <span>gameMode?.userInterface</span>. This pattern is called <em>optional chaining</em>. In this specific case the <span>userInterface</span> variable is only being accessed if <span>gameMode</span> actually contains a value. More generally, optional chaining can be used to call methods and access properties on values that might be <span>nil</span>, without causing an runtime error.</p>
<p>[Theoretical problems] Note that the property observer that we’ve implemented on <span>selectedGameMode</span> is not entirely safe. Whenever the game mode gets set, we add a new UI onto the <span>MainScene</span> - without removing a a UI that potentially already exists. Theoretically this could cause multiple UIs to be displayed on <span>MainScene</span>. However, you’ll see a little later in this chapter that this isn’t a practical concern for our game.</p>
<p>In the last line of the property observer we set the <span>zOrder</span> of the game mode UI to <span>DrawingOrder.ScoreBoard.rawValue</span>. You probably remember that we have used an enum to keep track of our drawing order when we implemented the object catching code.</p>
<p>Here we have another use case for such a <span>DrawingOrder</span> enum. The UI of the current game mode should be rendered on top of all gameplay elements.</p>
<p>This means we need a new <span>DrawingOrder</span> enum for <span>MainScene</span>!</p>
<p>Add the following enum to <span>MainScene.swift</span>:</p>
<pre><code>  enum DrawingOrder: Int {
    case GameplayElements
    case ScoreBoard
  }</code></pre>
<p>Having the scoreboard as the last case (with the highest integer value), means that the game mode UI will be rendered above the <em>GameplayElements</em>.</p>
<p>Additionally, we need to assign the <span>.GameplayElements</span> z-order to the pot and the spawned objects.</p>
<p>Extend the <span>didLoadFromCCB</span> method in <span>MainScence</span> to set the pot’s z-order:</p>
<pre><code>  override func onEnterTransitionDidFinish() {
    super.onEnterTransitionDidFinish()
    
    userInteractionEnabled = true
    (*@\colorbox{light-gray}{pot.zOrder =
    DrawingOrder.GameplayElements.rawValue}@*)
    
    // spawn objects with defined frequency
    schedule(&quot;spawnObject&quot;, interval: spawnFrequency)
  }</code></pre>
<p>We also need to set an initial z-order for every spawned object.</p>
<p>Extend the <span>spawnObject</span> method to set an initial z-order value:</p>
<pre><code>  ...
  fallingObject.position = spawnPosition
  (*@\colorbox{light-gray}{fallingObject.zOrder =
  DrawingOrder.GameplayElements.rawValue}@*)
  
  addChild(fallingObject)
}</code></pre>
<p>Now the UI will be rendered in front of any game objects!</p>
<p>We have successfully instantiated a game mode - we can now move on to the code that will communicate with it.</p>
<p>Let’s start by calling the <span>gameplayStep(mainScene:, delta:)</span> method. This method needs to be called from within the <span>update:</span> method of <span>MainScene</span>. Additionally to calling the method we need to capture the return value to see wether the current game is over or not.</p>
<p>Add the following statements to the end of the <span>update:</span> method of <span>MainScene</span>:</p>
<pre><code>let isGameOver = gameMode?.gameplayStep(self, delta: delta)
if let isGameOver = isGameOver {
  if (isGameOver) {
    self.gameOver()
  }
}</code></pre>
<p>We call the step method of our delegate, passing a reference to <span>self</span> and the <span>delta</span> value. We store the boolean result and use it to check whether the game over condition occurred or not. If the game is over we call the <span>gameOver</span> method.</p>
<p>We should add the <span>gameOver</span> method next. For now, all it will do is switch back to the start scene of our game. Later on we will display a popup that summarizes the player’s results.</p>
<p>Add the <span>gameOver()</span> method to <span>MainScene</span>:</p>
<pre><code>func gameOver() {
  let startScene = CCBReader.loadAsScene(&quot;StartScene&quot;)
  let transition = CCTransition(crossFadeWithDuration: 0.7)
  CCDirector.sharedDirector().replaceScene(startScene, withTransition: transition)
}</code></pre>
<p>All we do is loading the <span>StartScene</span> and presenting it with a cross fade transition.</p>
<p>Now, all that is left is calling the <span>GameMode</span> when objects have been dropped or caught. Let’s begin with dropped objects.</p>
<p>Extend the <span>performMissedStep:</span> method to call the game mode delegate:</p>
<pre><code>func performMissedStep(fallingObject:FallingObject) {
  // check if falling object is below the screen boundary
  if (CGRectGetMaxY(fallingObject.boundingBox()) &lt; CGRectGetMinY(boundingBox())) {
    (*@\colorbox{light-gray}{gameMode?.gameplay(self, droppedFallingObject:
    fallingObject)}@*) 
    ...
  }
}</code></pre>
<p>We again use optional chaining to only call the <span>gameplay(mainScene:, droppedFallingObject:)</span> method if <span>gameMode</span> actually contains a value.</p>
<p>As a last step implement the same functionality for caught objects.</p>
<p>Extend <span>performCaughtStep:</span> with a call to the game mode delegate:</p>
<pre><code>func performCaughtStep(fallingObject:FallingObject) {
  // if the object was caught, remove it as soon as soon as it is entirely contained in the pot
  if (CGRectContainsRect(catchContainer.boundingBox(), fallingObject.boundingBox())) {
    (*@\colorbox{light-gray}{gameMode?.gameplay(self, caughtFallingObject:
    fallingObject)}@*) 
    ...
  }
}</code></pre>
<p>Now the game modes and all the communication between the selected game mode and <span>MainScene</span> should be set up correctly. Finally we can test the game mode selection.</p>
<p>Run the app and select the endless game mode, you should see something similar to the following screen once the game starts:</p>
<div class="figure">
<img src="images/Chapter7/endless_game_with_ui.png" alt="The endless game mode features a survival time label and a health bar" />
<p class="caption">The endless game mode features a survival time label and a health bar</p>
</div>
<p>You should see the health bar grow and shrink according to the game mode rules that we implemented; finally all the parts have come together.</p>
<p>Currently the automatic transition from the main scene back to the start scene, as soon as the game ends, is a little unexpected. It’s typical for games to present a summary after each session the player has completed. In the next section we’ll add a game over popup to our game.</p>
<h2 id="adding-a-game-over-popup">Adding a Game Over Popup</h2>
<p>Whenever a session ends, either because of a game over situation or because the time has run out, we want to present a popup that shows the results of this session. The popup should also provide easy ways to play the same game mode again and to switch back to the start scene.</p>
<p>By the end of this section we will have built a popup that looks like this:</p>
<div class="figure">
<img src="images/Chapter7/game_over_popup.png" alt="A popup at the end of each playing session summarizes the player’s results" />
<p class="caption">A popup at the end of each playing session summarizes the player’s results<span data-label="fig: gameoverpopup"></span></p>
</div>
<p>We will get started by creating this new UI element in <span>SpriteBuilder</span>, then we will work on integrating it in code.</p>
<h3 id="setting-up-the-popup-in-spritebuilder">Setting up the Popup in <span>SpriteBuilder</span></h3>
<p>We’ll start by creating a new <span>CCB File</span> for our popup.</p>
<p>Create a new <span>CCB File</span> in <span>SpriteBuilder</span>. Select <em>Layer</em> as the type. <strong>Choose the size to be <em>(400, 300)</em></strong> and name the file <span>GameOverPopup</span>.</p>
<p>We will center the popup when we present it. Centering is a lot easier when the anchor point of the popup is at (0.5, 0.5).</p>
<p>Select the root node of <span>GameOverPopup</span> and change the <em>Anchor point</em> to (0.5, 0.5).</p>
<p>Next, we’ll add the background for the popup. As you might have seen in figure [fig: gameover<sub>p</sub>opup] our popup has rounded corners. The easiest way to accomplish rounded corners in <span>Cocos2D</span> is using a stretchable image. The specific type of image we want to use is called a <em>9 slice</em> image. 9 slices images are divided into stretchable and non-stretchable parts. Using 9 slices images we can use small images and scale them to arbitrary dimensions without distorting the non-scalable parts of the image.</p>
<p>Here’s an illustration of how a 9 slice image works:</p>
<div class="figure">
<img src="images/Chapter7/9_slice.png" alt="A 9 slice image is divided into stretchable and non-stretchable regions" />
<p class="caption">A 9 slice image is divided into stretchable and non-stretchable regions</p>
</div>
<p>In the example above we have a blue image with rounded corner. If we want to scale that image, it’s important that the corners don’t get scaled, otherwise they would be distorted. <span>SpriteBuilder</span> allows us to define the scalable area of 9 slice images, that way we can choose a scalable area that is appropriate for each asset. The assets you have downloaded include an image with rounded corners. We’ll use that for the background of our popup.</p>
<p>Drag a <em>Sprite 9 Slice</em> from the node library and add it to the root node of <span>GameOverPopup.ccb</span>.</p>
<p>Set up the sprite 9 slice as following:</p>
<ol>
<li><p>Set the <em>Position type</em> to <em>percent of parent container</em> for <em>x</em> and <em>y</em> position</p></li>
<li><p>Set the <em>Position</em> to <em>(50, 50)</em></p></li>
<li><p>Set the <em>Content size type</em> to <em>percent of parent container</em> for <em>width</em> and <em>height</em></p></li>
<li><p>Set the <em>Width</em> to <em>(100%, 100%)</em></p></li>
<li><p>Set the <em>Anchor point</em> to <em>(0.5, 0.5)</em></p></li>
<li><p>Set the <em>Sprite frame</em> to <em>assets/popup-background.png</em></p></li>
<li><p>Set the <em>Opacity</em> to <em>0.95</em></p></li>
<li><p>Select a <em>light blue</em> color</p></li>
</ol>
<p>At this point your stage should look like this:</p>
<p><img src="images/Chapter7/9_slice_setup.png" alt="image" /></p>
<p>Note, that the asset <span>popup-background.png</span> has a white background. That allows us to create a sprite with rounded corners of any color. You might also have realized that the sprite 9 slice scales correctly without that we hat to define a scalable and non-scalable region. That’s because <span>SpriteBuilder</span> provides default values that work for many sprites. When you’ve selected a sprite 9 slice you’ll see the following entry in the <em>Item properties</em> tab:</p>
<p><img src="images/Chapter7/9_slice_settings.png" alt="image" /></p>
<p>These values are expressed in percent of the image size. This means the non-scalable part of the image is defined as 33% of the image size from each edge. These settings work well for many 9 slice image. If you ever run into problems with a 9 slice image (i.e. your image looks distorted), you now know where to change these settings.</p>
<p>Now, we’ll add the label that displays the highscore when the game is over. We’ll add this label and the two buttons as children to the sprite 9 slice because we will be adding a little animation to the popup that will scale it up. We want the entire popup content to scale with the sprite 9 slice.</p>
<p>Drag a <em>Label TTF</em> to the stage. Drop it onto the <em>CCSprite9Slice</em> in the timeline to make the label a child of the sprite.</p>
<p>Set the label up as following:</p>
<ol>
<li><p>Set the <em>Position reference corner</em> to <em>Top-left</em></p></li>
<li><p>Set the <em>X</em> <em>Position type</em> to <em>percentage of parent container</em></p></li>
<li><p>Set the <em>Anchor Point</em> to <em>(0.5, 0.5)</em></p></li>
<li><p>Set the <em>Position</em> to <em>(50, 30)</em></p></li>
<li><p>Set the label text to <em>You have survived 10 seconds!</em>. This is a placeholder text. We’ll set the actual text dynamically in code</p></li>
<li><p>Set the <em>Font name</em> to <em>Optima-Bold</em></p></li>
<li><p>Set the <em>Font size</em> to <em>30</em></p></li>
<li><p>Set the <em>Size type</em> of the <em>Width</em> of the <em>Dimensions</em> to <em>percentage of parent container</em>:</p>
<p><img src="images/Chapter7/set_dimensions.png" alt="image" /></p>
<p>Labels resize dynamically based on their content, the <em>Dimensions</em> size determines the maximum size for the label. As soon as the label reaches the maximum width that we define, it will start breaking into new lines</p></li>
<li><p>Set the the Dimensions to <em>(95, 0)</em></p></li>
<li><p>Set the horizontal alignment to <em>Center</em></p></li>
<li><p>Set the draw color to <em>black</em></p></li>
<li><p>Set the outline color to <em>white</em></p></li>
<li><p>Set the outline width to <em>4</em></p></li>
<li><p>Set up a code connection to <em>Owner var</em> and name it <em>gameOverPopUpHighscoreLabel</em></p></li>
</ol>
<p>By providing the <em>owner</em> of the popup with access to the label we avoid providing a custom class for the popup. Instead, whichever class displays this popup can set itself as the owner and modify the popup appropriately. For UI components that don’t have any custom behavior I prefer this approach over providing custom classes. Earlier we have used it as well, as we set up the scoreboards for our different game modes.</p>
<p>Now we’re going to create two buttons, one to play another round of the current game mode, a second one to return to the main menu.</p>
<p>Drag a <em>Button</em> to the stage. Drop it onto the <em>CCSprite9Slice</em> in the timeline to make the label a child of the sprite.</p>
<p>Configure the button like this:</p>
<ol>
<li><p>Set the <em>X</em> <em>Position type</em> to <em>percentage of parent container</em></p></li>
<li><p>Set the <em>Position</em> to <em>(30, 55)</em></p></li>
<li><p>Set the <em>Preferred size</em> to <em>(120, 40)</em>. Buttons resize automatically based on their content, the preferred size determines the minimum size of the button</p></li>
<li><p>Set the <em>Title</em> to <em>Back to Menu</em></p></li>
<li><p>Set the <em>Font name</em> to <em>Optima-Bold</em></p></li>
<li><p>Set up a <em>selector</em> in the code connections tab. Name it <em>backToMenu</em> and set the target to <em>Owner</em>.</p></li>
</ol>
<p>Just as we set up the <em>code connection</em> of the label with the owner, we will also invoke the button callbacks on the owner - we want to avoid creating a custom class for this simple popup.</p>
<p>You can now copy this button to create the second one.</p>
<p>Copy the button that we just created. Apply the following changes:</p>
<ol>
<li><p>Change the <em>Position reference corner</em> to <em>Bottom-right</em></p></li>
<li><p>Set the <em>Position</em> to <em>(30, 55)</em></p></li>
<li><p>Change the <em>Title</em> to <em>Play again</em></p></li>
<li><p>Change the <em>selector</em> in the code connections tab to <em>playAgain</em></p></li>
</ol>
<p>Now the popup should look exactly as depicted in figure [fig: gameover<sub>p</sub>opup], at the beginning of this chapter.</p>
<p>We’re almost done with designing the popup in <span>SpriteBuilder</span>. However, so far we haven’t considered how this popup is going to be presented. It would be weird if it would suddenly appear at the end of the game, without any visual transition. Especially iOS users are used to smooth transitions and UI elements that are presented and dismissed with animations - our game should live up to these standards! <span>SpriteBuilder</span>’s timeline editor makes implementing this a matter of seconds.</p>
<p>To present the popup smoothly we will use a scale animation (very similiar to the animation that iOS uses for its alert views). Here’s what it will look like:</p>
<div class="figure">
<img src="images/Chapter7/popup_animation.png" alt="We make the popup appear over 13 frames by animating its scale property" />
<p class="caption">We make the popup appear over 13 frames by animating its scale property<span data-label="fig: animategamoverpopup"></span></p>
</div>
<p>The animation will have a length of 13 frames. We will scale the popup from 0% to 110% and finally to 100% of its final size. This approach creates a nice little bounce animation when the popup appears.</p>
<p>Instead of creating a new timeline we will use the <em>Default Timeline</em> that is provided by <span>SpriteBuilder</span> for every <span>CCB File</span>. The default timeline has the <em>autoplay</em> option activated, which means that it runs as soon as the root node of the <span>CCB File</span> is added to an active scene. By coincidence this is exactly the behavior we want: as soon as the popup is added to a scene we want this animation to play once. We can leave the <em>autoplay</em> option activated and don’t need to trigger this animation in code.</p>
<p>Note that <span>SpriteBuilder</span> does not allow us to add keyframe based animations to the root node of <span>CCB File</span>, instead we will animate the <em>CCSprite9Slice</em> which has all other elements of the popup as its children.</p>
<p>Set up the animation for the popup:</p>
<ol>
<li><p>Select the <em>CCSprite9Slice</em> in the timeline. Since this animation is very short, you should use the timeline’s maximum zoom level to place the keyframes accurately. Drag the zoom lever in the top right corner all the way to the right:</p>
<p><img src="images/Chapter7/timeline_zoom.png" alt="image" /></p></li>
<li><p>Now, create three keyframes for our animation. Create one at <em>00:00:00</em>, one at <em>00:00:09</em> and a third one at <em>00:00:13</em>. You can create the <em>scale</em> keyframes by hitting the <em>S</em> key or by using the <em>Animation</em> menu.</p></li>
<li><p>Next, set the scale values by double-clicking onto each of the keyframes. As show in figure [fig: animate<sub>g</sub>amover<sub>p</sub>opup] we want the values to be <em>0.0</em>, <em>1.0</em> and <em>1.1</em>.</p></li>
</ol>
<p>You can now run the animation and you should see a nice bounce effect. If you have ever paid close attention to the animations of system elements on iOS you will realize that something with this animation still doesn’t feel exactly right. Why?</p>
<p>As a default setting <span>SpriteBuilder</span> uses linear interpolation between keyframes.[timeline<sub>i</sub>nterpolation] This results in animations that move smoothly at a constant speed. However, real life objects seldom move at a constant speed. Instead they accelerate an decelerate. Believe it or not, the difference between a linear animation and an accelerated one is noticeable, even if the entire animation only lasts 13 frames.</p>
<p>Since the developers of <span>Cocos2D</span> are aware of this effect, they have provided us with a whole bunch of different interpolations. Once you have created two keyframes and a pink bar appears between them you can select between all of the variations by right-clicking onto the bar.</p>
<p>Many developers have done a good job of visualizing the different interpolation types. Kirill Muzykov has create a nice blog post with animated diagrams of the different interpolations that <span>Cocos2D</span> provides: <a href="http://kirillmuzykov.com/cocos2d-iphone-easing-examples/" class="uri">http://kirillmuzykov.com/cocos2d-iphone-easing-examples/</a>.</p>
<p>For this animation we are going to use the <em>Ease In</em> interpolation.</p>
<p>Right-click onto the segment between the <strong>first</strong> and the <strong>second</strong> keyframe and select <em>Ease In</em> as the interpolation function:</p>
<p><img src="images/Chapter7/timeline_ease_in.png" alt="image" /></p>
<p>Now you can run the animation again. You should notice that it is looking much better! These are the small details that catch the player’s attention.</p>
<p>We are ready to present this popup in code!</p>
<h2 id="presenting-the-popup-in-code">Presenting the Popup in Code</h2>
<p>As always, let’s get started by setting up properties for the code connections we’ve added in <span>SpriteBuilder</span>. The code to present the popup will be part of <span>MainScene</span>. In <span>SpriteBuilder</span> we’ve set up all code connections for the game over popup to be connected to the <em>Owner</em>. Since <span>MainScene</span> will be the owner of <span>GameOverPopup</span> we need to add code connection variables and callback methods there.</p>
<p>Let’s first add the property for the label on the game over popup.</p>
<p>Add the following property to <span>MainScene.swift</span>:</p>
<pre><code>weak var gameOverPopUpHighscoreLabel: CCLabelTTF!</code></pre>
<p>This property will allow us to change the presented text on the game over popup from within <span>MainScene</span>. Later we’ll use it to present the final score at the end of each game.</p>
<p>Our game over popup should be presented above all other content of <span>MainScene</span>. We should add a new entry to the <span>DrawingOrder</span> enum that places the popup at the highest z-order.</p>
<p>Extend the drawing order enum by adding a case for our new popup:</p>
<pre><code>enum DrawingOrder: Int {
  case GameplayElements
  case ScoreBoard
  case GameOverPopup
}</code></pre>
<p>Now we’re set up to work on the code that adds the popup to <span>MainScene</span> as soons as the game ends. We’ll modify the existing <span>gameOver</span> method in this step. So far <span>gameOver</span> transitions back to the <span>StartScene</span> when the game ends. We can remove all of that code for now.</p>
<p>Change the <span>gameOver</span> method, so that it no longer switches back to the <span>StartScene</span>:</p>
<pre><code>func gameOver() {
  userInteractionEnabled = false
  isDraggingPot = false
  presentGameOverPopup()
}</code></pre>
<p>In the new implementation of <span>gameOver</span> we’re disabling the user interaction on the <span>MainScene</span>. This means that <span>MainScene</span> will no longer receive touch events after the game ends. Without this line it would be possible for the user to drag the pot across the screen, even though the game has ended. Typically you want to disable all interactions between the player and any game elements as soon as a game ends.</p>
<p>In addition to disabling user interaction, we also set <span>isDraggingPot</span> to <span>false</span>. Ongoing touch events are not cancelled when user interaction gets disable. If a player would be dragging the pot when the game ends, they could go one forever. With <span>isDraggingPot</span> disabled, the code within <span>touchMoved</span> will not be performed and the dragging is interrupted immediately.</p>
<p>Lastly, we’re calling the <span>presentGameOverPopup</span> method that we haven’t implemented yet. As you’ll see shortly, presenting the popup involves quite a few lines of boilerplate code so it makes sense to bundle this functionality into a separate method.</p>
<p>Let’s implement <span>presentGameOverPopup</span> now. There aren’t a lot of new concepts involved in this method, so I’ll provide the entire implementation and will discuss the details afterwards.</p>
<p>Add the following lines to the end of the <span>MainScene</span> class, directly before the closing curly braces of the class definition:</p>
<pre><code>func presentGameOverPopup() {
  let gameOverPopup = CCBReader.load(&quot;GameOverPopup&quot;, owner:self)
  
  // workaround because CCPositionTypeNormalized cannot be used at the moment
  // https://github.com/spritebuilder/SpriteBuilder/issues/1346
  gameOverPopup.positionType = CCPositionType(
    xUnit: .Normalized,
    yUnit: .Normalized,
    corner: .BottomLeft
  )
  
  gameOverPopup.position = ccp(0.5, 0.5)
  gameOverPopup.zOrder = DrawingOrder.GameOverPopup.rawValue
  
  gameOverPopUpHighscoreLabel.string = gameMode?.highscoreMessage()
  
  addChild(gameOverPopup)
}</code></pre>
<p>In the first line we are loading the <span>GameOverPopup.ccb</span> using the <span>CCBReader</span>, we are setting <span>MainScene</span> as the owner.</p>
<p>Next, we’re setting up the position type of the popup. We want the popup to be presented centered on the screen. The easiest way to do that is to use the <span>Normalized</span> position type (which is called <em>Percent of parent container</em> in <span>SpriteBuilder</span>). We need to configure the position type in code, because <span>SpriteBuilder</span> does not support setting the position type of the root node of a <span>CCB File</span>. If you select the root node of <span>GameOverPopup.ccb</span>, you’ll see that the control is disabled:</p>
<div class="figure">
<img src="images/Chapter7/root_node_disabled_position_type.png" alt="It isn’t possible to change the position type or position of the root node in SpriteBuilder" />
<p class="caption">It isn’t possible to change the position type or position of the root node in <span>SpriteBuilder</span></p>
</div>
<p>When setting the position type in code, we run into a small Swift &lt;-&gt; Objective-C related issue. The way that many <span>Cocos2D</span> constants are defined is incompatible with Swift, these constants are not available to Swift classes. Usually we could simply set the position type to <span>CCPositionTypeNormalized</span>, but because of this issue we need to construct the position type manually (if you are interested in the details you can read about the issue here: <a href="https://github.com/spritebuilder/SpriteBuilder/issues/1346" class="uri">https://github.com/spritebuilder/SpriteBuilder/issues/1346</a>).</p>
<p>After we’ve set up the position type we center the node by setting the position to <em>(0.5, 0.5)</em> and we set the <span>zOrder</span> to render this popup on top of all other game content.</p>
<p>Then we configure which text is displayed on the popup. We haven’t implemented this on the game mode classes yet, but we’re adding a <span>highscoreMessage</span> method to each game mode that will return a suitable highscore message for the current game state. This way each game mode can present a different message at the end of the game. This design makes it easy to add more game modes in future. We’ll discuss the <span>highScoreMessage</span> method in detail as soon as we implement it.</p>
<p>In the next line we add the game over popup to the gameplay scene. Adding the popup will trigger it’s timeline to start playing. That will scale the popup from 0% to 100% size with the animation that we have defined in <span>SpriteBuilder</span>.</p>
<p>With this method in place we’re getting close to presenting the popup! We’ll need to satisfy two more code connections: the callback methods for both buttons on the popup.</p>
<p>Then we’ll need to extend our game modes so that they capture a highscore that we can display within the popup.</p>
<p>Let’s start with the button and implement the callback for the <em>Back to menu</em> button. All this button does is bring us back to the main scene, so the implementation is very simple.</p>
<p>Add the <span>backToMenu</span> method below the <span>presentGameOverPopup</span> method in <span>MainScene.swift</span>:</p>
<pre><code>func backToMenu() {
  let startScene = CCBReader.loadAsScene(&quot;StartScene&quot;)
  let transition = CCTransition(crossFadeWithDuration: 0.7)
  CCDirector.sharedDirector().replaceScene(startScene, withTransition: transition)
}</code></pre>
<p>Nothing special here, this is the code that used to live in the <span>gameOver</span> method - when the player hits the <em>Back to menu</em> button, we transition back to <span>StartScene</span>.</p>
<p>The <em>Play again</em> button is a little bit more exciting. This is a feature that you’ll want to add to many types of games and the implementation isn’t very complicated. The easiest way to restart the game is to create a new instance of the <span>MainScene</span> class and replace the currently active scene with that new one. I’ve often seen beginners in game development write code to reset different state variables in their gameplay scene, in order to start a new match or a new round of the same game. Creating a new instance of the core gameplay class is the simplest and most reliable way of resetting the entire state of the game.</p>
<p>For this specific game there’s one small gotcha that we need to avoid. The <span>MainScene</span> needs to know which gameplay mode has been selected. When a player hits the <em>Play again</em> button, we want to start the <em>same</em> game mode that the player has been playing up until then. This means that as we create a new instance of <span>MainScene</span>, we need to take care of preserving the selected game mode.</p>
<p>With all of this in mind, let’s add the <span>playAgain</span> method.</p>
<p>Add the <span>playAgain</span> method below the <span>backToMenu</span> method:</p>
<pre><code>func playAgain() {
  let mainSceneContainer = CCBReader.loadAsScene(&quot;MainScene&quot;)
  let mainScene = mainSceneContainer.children[0] as! MainScene
  mainScene.selectedGameMode = selectedGameMode
  let transition = CCTransition(crossFadeWithDuration: 0.7)
  CCDirector.sharedDirector().replaceScene(mainSceneContainer, withTransition: transition)
}</code></pre>
<p>Remember, when we use the <span>CCBReader.loadAsScene()</span> method, the root node from the loaded <span>CCB File</span> is added as a child to a <span>CCScene</span> instance. That is why we need to access the first child of the loaded scene to get a reference to the new <span>MainScene</span> instance. With that reference at hand we set the <span>selectedGameMode</span> of the new <span>MainScene</span> to be the same as the currently selected game mode. The rest is business as usual; replacing the scene with an animated transition.</p>
<p>And that’s all there is; you now know how to add a <em>play again</em> feature to your game. As you’ve seen it can be done with very little effort in <span>Cocos2D</span>!</p>
<p>Now we’ll extend the game modes to provide individual highscore messages, so that we have something to display on our highscore popup.</p>
<h2 id="providing-a-highscore-for-each-game-mode">Providing a Highscore for each Game Mode</h2>
<p>Whenever we want to extend the functionality of our game modes we should start by adding the new features to the <span>GameMode</span> protocol.</p>
<p>Add the following method to the <span>GameMode</span> protocol:</p>
<pre><code>func highscoreMessage() -&gt; String</code></pre>
<p>Now every game mode will be required to implement a <span>highscoreMessage</span> method. Let’s go ahead and add them, so we can finally see the popup in action.</p>
<p>Let’s start with the <span>EndlessGameMode</span>. When the <span>EndlessGameMode</span> ends, we want to display how many seconds a player has survived.</p>
<p>Add the following implementation of <span>highscoreMessage</span> to <span>EndlessGameMode</span>:</p>
<pre><code>func highscoreMessage() -&gt; String {
  let secondsText = Int(survivalTime) == 1 ? &quot;second&quot; : &quot;seconds&quot;
  return &quot;You have survived \(Int(survivalTime)) \(secondsText)!&quot;
}</code></pre>
<p>The most exciting part of this implementation is the ternary operator that we use to determine whether or not we need to pluralize the term <span>second</span>.</p>
<p>Whenever the timed game mode ends we want to display the accomplished score. The implementation of <span>highscoreMessage</span> is very similar for both game modes.</p>
<p>Implement the <span>highscoreMessage</span> method in <span>TimedGameMode</span> as following:</p>
<pre><code>func highscoreMessage() -&gt; String {
  let pointsText = points == 1 ? &quot;point&quot; : &quot;points&quot;
  return &quot;You have scored \(Int(points)) \(pointsText)!&quot;
}</code></pre>
<p>Awesome! Now we have all the parts together to actually test our new popup. Run the game on the simulator or on a phone, lose one of the two game modes, and see what happens.</p>
<p>You should see something very similar to this:</p>
<div class="figure">
<img src="images/Chapter7/endless_popups.png" alt="An endless amount of popups is filling up the screen (and our main memory)" />
<p class="caption">An endless amount of popups is filling up the screen (and our main memory)</p>
</div>
<p>As soon as the game ends our popup gets presented. But not only once; new popups are added endlessly. Why is that happening? We’ll look into fixing this in the next section.</p>
<h2 id="tweaking-the-game-over-popup">Tweaking the Game Over Popup</h2>
<p>The issue we are experiencing is very common among developers that are implementing their first game over popup. What is going wrong?</p>
<p>We are presenting the popup from within the <span>update:</span> method. That method gets called 60 times a second. We are currently not checking whether or not we’ve already presented the popup. Instead, we present a new game over popup every single frame because the game over condition is always met. If you have the patience to wait long enough you will experience a crash due to excessive use of memory.</p>
<p>The fix for this problem is pretty straightforward. We’ll add a boolean flag to <span>MainScene</span> that will indicate whether we are in <em>game over</em> state or not. If we are in game over state, we will skip the entire <span>update:</span> method. That way we will no longer check if the game over condition is met which means we’ll no longer present an endless amount of popups. This approach has another advantage: since we’ve implemented all object movement inside of the <span>update:</span> method, all objects will freeze as soon as the game ends. That’s the behavior that most players expect.</p>
<p>Let’s add a new property to reflect the state of the game.</p>
<p>Add the following property to <span>MainScene</span>:</p>
<pre><code>private var gameEnded = false</code></pre>
<p>By default, <span>gameEnded</span> is <span>false</span>, as soon as the game ends we’ll set it to <span>true</span>. The most convenient place to set the flag is inside of the <span>gameOver</span> method, since this method is called as soon as the game ends.</p>
<p>Modify the <span>gameOver</span> method of <span>MainScene</span> to look as following:</p>
<pre><code>func gameOver() {
  (*@\colorbox{light-gray}{gameEnded = true}@*)
  userInteractionEnabled = false
  isDraggingPot = false
  presentGameOverPopup()
}</code></pre>
<p>Now, we’ll also need to modify the <span>update:</span> method to check for this flag.</p>
<p>Add the following statements to the beginning of the <span>update:</span> method:</p>
<pre><code>override func update(delta: CCTime) {
  if (gameEnded) {
    return
  }
...
}</code></pre>
<p>If the <span>isGameOver</span> flag is set we immediately return from the <span>update:</span> method, without performing any game logic.</p>
<p>Now you can run the game again, and you should notice that our issue is fixed.</p>
<p>However, there’s another small problem we should work on. When the game ends and the popup appears, we have multiple score displays on screen. The popup informs us about the final score, and in the background, behind the popup, we can see the scoreboard that is displayed while the game is running.</p>
<div class="figure">
<img src="images/Chapter7/no_ui_fadeout_popup.png" alt="The player is confronted with score information in two places. The popup and the scoreboard contain the same information." />
<p class="caption">The player is confronted with score information in two places. The popup and the scoreboard contain the same information.</p>
</div>
<p>To fix this, we’ll hide the scoreboard UI as soon as the game over popup is presented. We’ll extend the <span>presentGameOverPopup</span> method to implement this.</p>
<p>Add the following three lines to the end of <span>presentGameOverPopup</span>:</p>
<pre><code>func presentGameOverPopup() {
  ...  
  let fadeOutAction = CCActionFadeOut.actionWithDuration(0.3) as CCAction
  gameMode?.userInterface.cascadeOpacityEnabled = true
  gameMode?.userInterface.runAction(fadeOutAction)
}</code></pre>
<p>Animated appearances and disappearances always look a lot better than unanimated ones. With <span>Cocos2D</span> we can accomplish visual effects with only a few lines of code, so we fade out the scoreboard UI instead of simply making it invisible.</p>
<p>With this code in place you can test the game once again. Now you should see a nicely presented popup with no duplicate information displayed behind it:</p>
<div class="figure">
<img src="images/Chapter7/ui_fadeout_popup.png" alt="Without the score information in MainScene this popup looks more polished" />
<p class="caption">Without the score information in <span>MainScene</span> this popup looks more polished</p>
</div>
<h2 id="summary-4">Summary</h2>
<p>Well done! In this chapter you have learned a lot about user interfaces in <span>SpriteBuilder</span> and <span>Cocos2D</span>. You know how to use scroll views, how to present popups and connect them to code efficiently and you’ve also learned how to implement a restart mechanism. Additionally we’ve spoken a lot about code design in this chapter. We have focused on creating this game in a way that decouples game modes from the actual gameplay. With this design it is very easy to add more game modes in future, and the lessons learned from this approach should apply to many of your original games as well.</p>
<p>In the next chapter we will look at how we can store highscores for this game. It is crucial to make your games competitive and to implement ways for players to track their progress as they play your game over longer periods of time. It’s one of the best ways of keeping players engaged with your products.</p>
<h1 id="persisting-highscores">Persisting Highscores</h1>
<p>The game we have built so far is clearly fun to play, however, if we want players to come back regularly we will need a highscore feature. Highscores will motivate players to improve their skills by playing the game frequently.</p>
<p>For this game we will keep the mechanism very simple. For each game mode we will store the highest score the player has achieved. These scores will only be stored locally on the device. Then we’ll extend the game over popup to show the current highscore and to inform the player in case she has beaten her old one.</p>
<p>[Why not Apple’s Game Center?] For this chapter I have considered using Apple’s <em>Game Center</em> framework, which provides features such as leaderboards and achievements. I’ve decided against it because it would require all readers to purchase an Apple Developer account (required settings for Game Center games are only available fo registered Apple Developers). If you are interested in adding <em>Game Center</em> support to your game you should read this tutorial: <a href="http://rebeloper.com/add-game-center-spritebuilder-app-swift/" class="uri">http://rebeloper.com/add-game-center-spritebuilder-app-swift/</a></p>
<p>Before adding this feature we should, once again, talk about the architecture of our game. Which class should be responsible for storing highscores?</p>
<p>Since each game mode defines its own game rules and keeps track of highscores during the game, it should also be responsible for persisting the highscores.</p>
<h2 id="extending-the-gamemode-protocol">Extending the GameMode Protocol</h2>
<p>We’ll start implementing this feature by extending the definition of the <span>GameMode</span> protocol. We’ll add a required method called <span>saveHighscore</span>. That method will be called from within <span>MainScene</span> as soon a game ends. All game modes will implement this method and perform the highscore storing code within it.</p>
<p>Open <span>GameMode.swift</span> and add the following method to the end of the protocol definition:</p>
<pre><code>func saveHighscore()</code></pre>
<p>Now that we’ve extended the definition of the protocol we need call this method from within <span>MainScene</span>. Whenever a game ends, we want to store the latest highscore of the current game mode. It makes the most sense to place this method call in the <span>gameOver</span> method.</p>
<p>Extend the <span>gameOver</span> method in <span>MainScene.swift</span> to look as following:</p>
<pre><code>func gameOver() {
  isGameOver = true
  userInteractionEnabled = false
  isDraggingPot = false
  (*@\colorbox{light-gray}{gameMode?.saveHighscore()}@*)
  presentGameOverPopup()
}</code></pre>
<p>This change was simple. Now let’s implement the highscore saving mechanism for both game modes.</p>
<h2 id="storing-highscores-for-the-endless-game-mode">Storing Highscores for the Endless Game Mode</h2>
<p>iOS provides us with a variety of options to persist application data. <em>Core Data</em> offers a feature-rich object persistence API that allows for advanced features such as search and migration between different versions of a data model. Through <span>NSKeyedArchiver</span> we are able to serialize objects and store them in files. Another option, preferred for simple tasks, is using the <span>NSUserDefaults</span> class to persist information.</p>
<p><span>NSUserDefaults</span> is a persistent key-value store with a very simple API. Here’s an example of we can store a highscore value:</p>
<pre><code>NSUserDefaults.standardUserDefaults().setInteger(20, forKey: &quot;highscore&quot;)</code></pre>
<p>All we need to provide as a key and a value - just as when working with a dictionary.</p>
<p>Retrieving the information is just as straightforward:</p>
<pre><code>let oldHigschore =
NSUserDefaults.standardUserDefaults().integerForKey(highscoreKey)</code></pre>
<p>Since we only want to score one integer per game mode, this simple API is ideal for our purposes.</p>
<p>Let’s start with the implementation for the <span>EndlessGameMode</span>.</p>
<p>Add the following two member definitions to <span>EndlessGameMode.swift</span>:</p>
<pre><code>private let highscoreKey = &quot;EndlessGameMode.Highschore&quot;
private var newHighscore = false</code></pre>
<p>We define a variable called <span>newHighscore</span> to keep track of whether or not the latest achieved score was a highscore. We will check this value when we generate the highscore message. If the latest score was a highscore, we will extend the message to congratulate the player.</p>
<p>We’ll also define a constant for the <em>key</em> that we use to store and retrieve the highscore from <span>NSUserDefaults.</span> When defining a key for working with <span>NSUserDefaults</span> it’s good practice to prefix it with the current class name. That avoids conflicts between different parts of your app that might store and access information in the user defaults.</p>
<p>Now we can implement the <span>saveHighscore</span> method. We’ll check if the latest score is higher than the current highscore. If that’s the case we will persist the latest score and set the <span>newHighscore</span> variable to <span>true</span>. Otherwise we’ll simply set <span>newHighscore</span> to <span>false</span>.</p>
<p>Add the following method to <span>EndlessGameMode.swift</span>:</p>
<pre><code>func saveHighscore() {
  let oldHigschore = NSUserDefaults.standardUserDefaults().integerForKey(highscoreKey)

  if (Int(survivalTime) &gt; oldHigschore) {
    // if this score is larger than the old highscore, store it
    NSUserDefaults.standardUserDefaults().setInteger(Int(survivalTime), forKey: highscoreKey)
    NSUserDefaults.standardUserDefaults().synchronize()
    newHighscore = true
  } else {
    newHighscore = false
  }
}</code></pre>
<p>Now we are conforming to the new <span>GameModeDelegate</span> protocol and are successfully storing new highscores! One interesting line that we did not discuss yet is the following:</p>
<pre><code>NSUserDefaults.standardUserDefaults().synchronize()</code></pre>
<p>This line forces <span>NSUserDefaults</span> to write the latest changes to disk immediately. This method is called periodically by default. If we however store more or less sensitive information, such as the latest highscore a player just achieved, we call the method explicitly. That way the changes are persisted right away, eliminating the risk of losing data if the app crashes or is quit by the user.</p>
<p>Now there’s a last step left. We should change the highscore message that we are displaying at the end of the game to include the player’s highscore. Further, if the player just beat her own highscore we want to display a special message to congratulate the player.</p>
<p>Replace the existing <span>highscoreMessage</span> method with the following one:</p>
<pre><code>func highscoreMessage() -&gt; String {
  let secondsText = &quot;second&quot;.pluralize(survivalTime)

  if (!newHighscore) {
    let oldHighscore = NSUserDefaults.standardUserDefaults().integerForKey(highscoreKey)
    let oldHighscoreText = &quot;second&quot;.pluralize(oldHighscore)
    
    return &quot;You have survived \(Int(survivalTime)) \(secondsText)! Your highscore is \(Int(oldHighscore)) \(oldHighscoreText).&quot;
  } else {
    return &quot;You have reached a new highscore of \(Int(survivalTime)) \(secondsText)!&quot;
  }
}</code></pre>
<p>One of the first things you might notice is that we’ve introduced a <span>pluralize</span> method on <span>String</span>. This method is part of the helpers (in <span>Helpers.swift</span>) that we’ve included right at the beginning of this project. Since we now have multiple occasions in which we need to use the pluralized form of a word, it makes sense to factor this functionality out and avoid code duplication. This <span>pluralize</span> method is very primitive, it will append and <em>s</em> to a word in case the integer passed to the method is unequal one. That is obviously not the correct way to pluralize all English words, but for our game in which we use <em>points</em> and <em>seconds</em> it works just fine.</p>
<p>In the first line of this method we determine whether we need to use the word <em>second</em> or <em>second<strong>s</strong></em> using the <span>pluralize</span> method.</p>
<p>Next, we check if the player has achieved a new highscore. If not, we display the latest score along with the current highscore. Otherwise we let the player know that he just reached a new highscore.</p>
<p>This is all it takes to build a simple highscore system! <span>NSUserDefaults</span> can go a pretty far way when storing this kind of simple information.</p>
<p>All that is left for this chapter is adding the same highscore functionality to the timed game mode.</p>
<h2 id="storing-highscores-for-the-timed-game-mode">Storing Highscores for the Timed Game Mode</h2>
<p>The implementation for the timed game mode is very similar to the one we’ve implemented just now. In fact they are so similar that I briefly thought about factoring the implementation out, so that it can be used by both game modes without duplicating code. However, I’ve decided not to follow through on that idea. I think the amount of duplicate code in this case isn’t large enough to require a more abstract but more complex solution. If you were to add a few more game modes this might change, for now we are going to accept some code duplication.</p>
<p>Since the implementation is so similar to what we’ve just seen, we won’t discuss it in the usual detail.</p>
<p>Add the <span>newHighscore</span> variable and the <span>highscoreKey</span> constant to <span>TimedGameMode.swift</span>:</p>
<pre><code>private let highscoreKey = &quot;TimedGameMode.Highschore&quot;
private var newHighscore = false</code></pre>
<p>These two properties are basically the same as in the <span>EndlessGameMode</span>.</p>
<p>Next, add the highscore saving method for <span>TimedGameMode</span>.</p>
<p>Add the following method to <span>TimedGameMode.swift</span>:</p>
<pre><code>func saveHighscore() {
  let oldHigschore = NSUserDefaults.standardUserDefaults().integerForKey(highscoreKey)
  
  if (points &gt; oldHigschore) {
    // if this score is larger than the old highscore, store it
    NSUserDefaults.standardUserDefaults().setInteger(points, forKey: highscoreKey)
    NSUserDefaults.standardUserDefaults().synchronize()
    newHighscore = true
  } else {
    newHighscore = false
  }
}</code></pre>
<p>And finally update the method that displays the highscore message.</p>
<p>Replace the existing <span>highscoreMessage</span> method within <span>TimedGameMode.swift</span> with the following one:</p>
<pre><code>func highscoreMessage() -&gt; String {
  let pointsText = &quot;point&quot;.pluralize(points)
  
  if (!newHighscore) {
    let oldHighscore = NSUserDefaults.standardUserDefaults().integerForKey(highscoreKey)
    let oldHighscoreText = &quot;point&quot;.pluralize(oldHighscore)
    
    return &quot;You have scored \(points) \(pointsText)! Your highscore is \(Int(oldHighscore)) \(oldHighscoreText).&quot;
  } else {
    
    return &quot;You have reached a new highscore of \(points) \(pointsText)!&quot;
  }
}</code></pre>
<p>Overall this implementation is almost identical to the Endless Game Mode’s one.</p>
<h2 id="summary-5">Summary</h2>
<p>Now we’ve implemented the entire highscore functionality for both game modes! I’ll admit that it is a very simple functionality, but it will definitely increase the motivation of players to come back to our game. Here’s what the popup message should look like once you’ve finished a game:</p>
<div class="figure">
<img src="images/Chapter8/Highscore_Message.png" alt="When the game ends the user retrieves information about their highscore" />
<p class="caption">When the game ends the user retrieves information about their highscore</p>
</div>
<p>We’re almost done with implementing this game and thus you are getting close to the end of this book. In the last chapter we will discuss something that makes the difference between a good game and a fantastic one: <em>Effects and Animations</em>! Get ready for the Grand Finale.</p>
<h1 id="effects-and-animations">Effects and Animations</h1>
<p>Up until this chapter we have built a fully functional game that could be shipped to the App Store! This last chapter will deal with polishing the game and making it more delightful. <span>SpriteBuilder</span> and <span>Cocos2D</span> provide powerful, yet simple to use tools to create visual effects and animations. In this chapter we will add light effects and we’ll use the <span>SpriteBuilder</span> timeline to bring some more motion to our gameplay.</p>
<h2 id="lighting-with-cceffects">Lighting with CCEffects</h2>
<p>Let’s start by adding some light effects to our game. Lighting effects can make a game feel a lot more polished. Here’s a comparison of what our game looks like right now, and how it will look once we’re completed this section:</p>
<div class="figure">
<img src="images/Chapter9/lighting_comparison.png" alt="Unlighted scene on the left, lighted scene on the right" />
<p class="caption">Unlighted scene on the left, lighted scene on the right<span data-label="lightingexample"></span></p>
</div>
<p>Most game engines require developers to write <em>shader programs</em> to use visual effects such as lighting. <span>Cocos2D</span> provides an API called <span>CCEffects</span> that implements many common visual effects, such as lighting, refraction, blur, etc. Using CCEffects we can enhance our games without needing to learn how to write shader programs.</p>
<p>To our delight, CCEffects can even be configured with <span>SpriteBuilder</span>! We can set up all of the lighting for this game with only a handful lines of code.</p>
<p>The first step of adding lighting to our game is understanding some of the theory that goes into lighting in 2D games.</p>
<h3 id="lighting-in-2d-games">Lighting in 2D Games</h3>
<p>The simplest way to light a 2D scene is to use brighter and darker colors, depending on the distance to a given light source, I’ll refer to this technique as <em>flat lighting</em>. Figure [lighting<sub>e</sub>xample] shows flat lighting on the background image of our game. Some areas of the background are lighter than others. The background is the lightest around the window and the kitchen light, the two light sources for our game.</p>
<p>Flat lighting comes entirely out of the box using <span>Cocos2D</span>. However, using flat lighting alone doesn’t create great visual effects. In 2D games lighting can be used to give objects a 3D feel. We are going to use that technique to enhance the look of our gameplay objects.</p>
<p>A lighting effect that creates a 3D feel can be accomplished by using <em>normal maps</em>. A normal map is a special kind of texture that describes the 3D surface of an object. That way the game engine can calculate how strong certain areas of a texture should be light up by a light source. Here’s what a normal map looks like:</p>
<div class="figure">
<img src="images/Chapter9/pot-bottom_NRM.png" alt="The normal map for the bottom part of the pot. Each color encodes information about the object’s surface" />
<p class="caption">The normal map for the bottom part of the pot. Each color encodes information about the object’s surface</p>
</div>
<p>And here’s a comparison that shows how lighting and normal maps together give the pot a 3D feel:</p>
<div class="figure">
<img src="images/Chapter9/pot_lighting_comparison.png" alt="No lighting on the left, lighting with normal map on the right" />
<p class="caption">No lighting on the left, lighting with normal map on the right</p>
</div>
<p>The comparison above shows that certain parts of the pot appear brighter and shinier. <span>Cocos2D</span> calculates the brightness for each part of the texture based on the normal map that we provide and the position of the light.</p>
<p>Lighting and normal maps for 2D games are topics that are worth dedicating entire books to (and there are a ton out there!) so for now we will stick with this overview of how lighting works. Even this basic knowledge will allows us to make the game look quite a bit better. You might wonder where the normal maps for our textures come from. The answer is: we need to create them ourselves.</p>
<h3 id="creating-normal-maps">Creating Normal Maps</h3>
<p>There are a bunch of tools that make it easy to create simple normal maps. For this book I’ve provided all of the normal maps for you, as part of the asset pack that you downloaded at the beginning of this book.</p>
<p>What if you want to create normal maps for your own game? The normal maps for this book have been created with the tool <em>CrazyBump</em> (<a href="http://www.crazybump.com/" class="uri">http://www.crazybump.com/</a>). CrazyBump uses shape detection to guess normal maps and the results have been great for me!</p>
<p>If you have complicated textures, or you need to polish the lighting effects in your game in great detail, you might want to resort to a tool that allows you to create a normal map manually. <em>SpriteIlluminator</em> (<a href="https://www.codeandweb.com/spriteilluminator" class="uri">https://www.codeandweb.com/spriteilluminator</a>) is a great tool for manually creating normal maps.</p>
<p>Since we already have all the normal maps we need, let’s dive right into <span>SpriteBuilder</span> and set up some light sources!</p>
<h3 id="setting-up-lighting-effects-in-spritebuilder">Setting up Lighting Effects in <span>SpriteBuilder</span></h3>
<p>Now that we have a basic understanding of 2D lighting it’s time to dive into the CCEffects API. There are three important components that we will be using:</p>
<dl>
<dt>CCEffectNode</dt>
<dd><p>is a container for all visual effects. If you want to apply effects to <span>CCSprite</span>s, all of them need to be the child of a <span>CCEffectNode</span>. In practice this means that you’ll mostly have a <span>CCEffectNode</span> as a container for your entire gameplay scene.</p>
</dd>
<dt>CCEffect</dt>
<dd><p>represents one of the different available visual effects, e.g. lighting, refraction, blur, etc. Currently effects can only be applied to <span>CCSprite</span>s. You add an effect to a sprite by instantiating a <span>CCEffect</span> subclass and assigning it to a <span>CCSprite</span>.</p>
</dd>
<dt>CCLightNode</dt>
<dd><p>is used in combination with the effect <span>CCEffectLighting</span> to define light sources.</p>
</dd>
</dl>
<p>To summarize what we’ve discussed so far:</p>
<ul>
<li><p>Effects can only be applied to <span>CCSprite</span>s</p></li>
<li><p>All affected sprites need to be a child of a <span>CCEffectNode</span></p></li>
<li><p>Light nodes are used together with the lighting effect and define light sources. Direction and brightness of these light nodes is used by <span>Cocos2D</span> to render lighting effects</p></li>
</ul>
<p>Here’s a simple scene graph that shows how the components play together:</p>
<p><img src="images/Chapter9/effect_setup.png" alt="image" /></p>
<p>All effects need to be applied to <span>CCSprite</span>s. All light sources and all sprites that want to be affected by lighting need to be children of a <span>CCEffectNode</span>.</p>
<p>We will only discuss a subset of the <span>CCEffects</span> API, but the good news is that it is very easy to use and therefore can be explored without much instruction!</p>
<p>There a many simple effects that can be added with a single line of code, such as <em>blur</em> or <em>saturation</em>. You can add all effects in code or in <span>SpriteBuilder</span>. You can change the relevant properties of a <span>CCEffect</span> in code, that alows you to animate effects. You can for example create a <em>saturation</em> effect that starts with full saturation and over time reduces the saturation until the sprite turns into a grayscale image.</p>
<p>[More on effects] If you want to learn a little bit more about effects in <span>Cocos2D</span> you should read our tutorial that introduces the <span>CCEffects</span> API (<a href="https://www.makeschool.com/tutorials/cocos2d-3-2-with-cceffects-is-coming" class="uri">https://www.makeschool.com/tutorials/cocos2d-3-2-with-cceffects-is-coming</a>).</p>
<p>This introduction gives us enough understanding to move to <span>SpriteBuilder</span> and set up our lighting.</p>
<p>Open the <span>SpriteBuilder</span> project and select the <span>MainScene.ccb</span> file.</p>
<ol>
<li><p>Drag an <em>Effect Node</em> from the node library to the timeline of <span>MainScene.ccb</span>; add it to the root level</p></li>
<li><p>Use the <span>Shift</span> key to select all of the nodes that are currently added to Main Scene (except for the <em>CCEffectNode</em>):</p>
<p><img src="images/Chapter9/copy_nodes_effect.png" alt="image" /></p></li>
<li><p>Drag the selected nodes onto the <em>CCEffect Node</em> to turn all of the nodes into children of the effect node. Your node hierarchy should look like this:</p>
<p><img src="images/Chapter9/node_hierarchy_effect2.png" alt="image" /></p></li>
<li><p>Set the <em>Content size type</em> of the effect node to <em>percentage of parent container</em></p></li>
<li><p>Set the <em>Content size</em> to <em>(100, 100)</em></p></li>
</ol>
<p>Now, we have the <span>CCEffectNode</span> set up which allows us to add visual effects!</p>
<p>Next, let’s look into adding the two light sources. We want the light sources to be placed on the window and above the stove. As you might remember, we are designing this game to work on 3.5 inch iPhones, 4 inch iPhones and on iPads.</p>
<p>In order to position the lights correctly for all of these device types we need to use a little trick. Simply using relative positioning with percentage values does not work. Here’s what the scene looks like on different device types when only using relative positioning:</p>
<div class="figure">
<img src="images/Chapter9/light_source_relative_position.png" alt="Relative positioning results in slightly different light positions for each device type" />
<p class="caption">Relative positioning results in slightly different light positions for each device type</p>
</div>
<p>We have set up the background image to be centered on all device types. Therefore the distance of the window and the stove from the screen edges varies. This means we cannot use the screen edges as reference points for positioning the lights.</p>
<p>The center of the background image is always at exactly the same position. The trick in this situation is to position the light sources relative to that center position. We can do so by adding an empty <span>CCNode</span> to the center of the scene and adding our two light sources as children of this container node.</p>
<p>[Previewing a scene on different device types] We have discussed this briefly in chapter [preview<sub>s</sub>creen<sub>s</sub>izes], but just as a short reminder: <span>SpriteBuilder</span> allows you to preview your scenes on different device types. To switch between different device types, go to the <em>Document</em> -&gt; <em>Resolution</em> menu:</p>
<p><img src="images/Chapter9/select_resolution.png" alt="image" /></p>
<p>You can also use the shortcuts displayed next to the device types!</p>
<p>Now we can start adding the center node and the two light sources.</p>
<p>First, let’s add the center node.</p>
<ol>
<li><p>Drag a plain <em>Node</em> from the node library and add it as a child of the <em>CCEffectNode</em></p></li>
<li><p>Set its <em>Position type</em> to be <em>percentage of parent container</em> for both <em>Width</em> and <em>Height</em></p></li>
<li><p>Set the <em>Position</em> to <em>(50, 50)</em></p></li>
<li><p>Rename the node to <em>light-container</em> by selecting the node in the timeline and hitting the return key</p></li>
</ol>
<p>Now we can add the light source for the window. We will discuss the interesting properties of our light sources in detail as soon as they are set up:</p>
<ol>
<li><p>Drag a <em>Light Node</em> from the node library and add it as a child of the <em>CCNode</em> that we created just now</p></li>
<li><p>Set the position of the light to <em>(-180, 90)</em></p></li>
<li><p>Set the <em>Diffuse Intensity</em> to <em>0.25</em></p></li>
<li><p>Set the <em>Specular Intensity</em> to <em>0.60</em></p></li>
<li><p>Set the <em>Ambient Intensity</em> to <em>0.73</em></p></li>
<li><p>Set the <em>Cutoff Radius</em> to <em>500.00</em></p></li>
<li><p>Set the <em>Half Radius</em> to <em>0.70</em></p></li>
<li><p>Set the <em>Depth</em> to <em>180</em></p></li>
</ol>
<p>Then, add the second light source:</p>
<ol>
<li><p>Drag a <em>Light Node</em> from the node library and add it as a child of the <em>light-container</em> that we created just now</p></li>
<li><p>Set the position of the light to <em>(140, 40)</em></p></li>
<li><p>Set the <em>Diffuse Intensity</em> to <em>0.20</em></p></li>
<li><p>Set the <em>Specular Intensity</em> to <em>0.60</em></p></li>
<li><p>Set the <em>Ambient Intensity</em> to <em>0.00</em></p></li>
</ol>
<p>Now, you should be able to switch between the different screen sizes and see that the lights are positioned correctly all the time! Let’s discuss some of the light properties that we just set up.</p>
<dl>
<dt>Diffuse Intensity</dt>
<dd><p>the intensity of the diffused portion of the light. Diffused light brightens nearby objects without resulting in a <em>shininess</em> effect. Diffused light is soft, directional light.</p>
</dd>
<dt>Specular Intensity</dt>
<dd><p>the intensity of the specular portion of the light. Specular light is a sharp, directional light. It causes reflections on surfaces of objects that are lit up.</p>
</dd>
<dt>Ambient Intensity</dt>
<dd><p>the intensity of the ambient portion of the light. Ambient light has no direction and the distance to objects in the scene is not relevant for this kind of light. All objects in the scene are lit up by ambient light in exactly the same way. This factor is used to set a base brightness.</p>
</dd>
<dt>Cutoff Radius</dt>
<dd><p>the reach of the light in points. Only nodes within the radius of the light will be lit up.</p>
</dd>
<dt>Half Radius</dt>
<dd><p>the portion of the radius at which the intensity of the light has fallen to half of its maximum value. You can choose a value between 0 and 1. A smaller value will create a sharper light, a higher value will create a smoother light.</p>
</dd>
<dt>Depth</dt>
<dd><p>defines how far away a light is from the objects that are lit up (in the z-dimension). The smaller the value, the more the objects are lit up from the side. A large value means that the light is far away from the pane, therefore the objects are lit from the front.</p>
</dd>
</dl>
<p>The last thing to note is that <span>Cocos2D</span> provides two different light types: <em>Point lights</em> and <em>Directional lights</em>. For this game we are only using point lights. You can change the type in the <em>Light type</em> dropdown in the property inspector. A point light only lights up objects that are within the cutoff radius, and objects that are further away from the light source are lit up less than closer objects.</p>
<p>Directional light sources produce <em>parallel light</em>. This means that light isn’t radiating from a specific point, but instead is coming from a specified direction.</p>
<p>[More details on lighting] The creator of <em>Sprite Illuminator</em>, one of the normal map tools mentioned earlier, has written a nice article on lighting in <span>SpriteBuilder</span> and <span>Cocos2D</span> that covers many light properties in detail: <a href="https://www.codeandweb.com/blog/2015/03/17/cocos2d-dynamic-lighting-tutorial
" class="uri">https://www.codeandweb.com/blog/2015/03/17/cocos2d-dynamic-lighting-tutorial
</a>. The source code annotations in <span>CCLightNode.h</span> of the <span>Cocos2D</span> framework also reveal many details about the different adjustable properties.</p>
<p>At this point we have the lighting set up, but we don’t see any change in our scene. Setting up lighting is a two step process in <span>Cocos2D</span>. We need to define the light sources, which we just did. Then we need to add the <em>Lighting effect</em> to sprites that shall be effected by these light sources. In this scene we want the background image and the pot to be affected by our light sources.</p>
<ol>
<li><p>Select the <em>background</em> sprite from the timeline</p></li>
<li><p>Add a lighting effect in the property inspector as following:</p>
<p><img src="images/Chapter9/add_lighting_effect.png" alt="image" /></p></li>
</ol>
<p>Now let’s apply the lighting effect to the pot.</p>
<ol>
<li><p>Open <em>Pot.ccb</em></p></li>
<li><p>Select <em>pot-top</em> and add a lighting effect in the same way you added it to the background</p></li>
<li><p>Adjust the <em>shininess</em> of this lighting effect to <em>0.3</em></p></li>
<li><p>Select <em>pot-bottom</em> and add a lighting effect</p></li>
<li><p>Adjust the <em>shininess</em> to <em>0.3</em></p></li>
<li><p>Use the shortkey <em>CMD + S</em> to save this <span>CCB File</span></p></li>
</ol>
<p>Now you should see the lighting taking effect! The last thing we need to do is add our normal maps. Adding normal maps will lead to reflections on game objects and make them fell 3D.</p>
<h3 id="assigning-normal-maps-in-spritebuilder">Assigning Normal Maps in <span>SpriteBuilder</span></h3>
<p>Now that our light sources and lighting effects are set up, let’s assign the normal maps to our sprites so that we get more detailed lighting. For the <em>pot-top</em> and <em>pot-bottom</em> sprite, we can set up the normal map in <span>SpriteBuilder</span>. The falling objects are spawned dynamically in code, we will look at how to set up their normal maps in the next section.</p>
<p>Adding normal maps to sprites is very simple in <span>SpriteBuilder</span>. In the property inspector of a <span>CCSprite</span> you can find a separate dropdown below the <em>Sprite frame</em> dropdown that allows us to assign a normal map:</p>
<p><img src="images/Chapter9/select_normal_map.png" alt="image" /></p>
<ol>
<li><p>Open <em>Pot.ccb</em></p></li>
<li><p>Select <em>pot-top</em> in the timeline</p></li>
<li><p>Set the normal map to <span>assetspot-top_NRM.png</span></p></li>
<li><p>Select <em>pot-bottom</em> in the timeline</p></li>
<li><p>Set the normal map to <span>assetspot-bottom_NRM.png</span></p></li>
<li><p>Use the shortkey <em>CMD + S</em> to save this <span>CCB File</span></p></li>
</ol>
<p>Great! Now you should see a nicely lit scene, with subtle reflections on the pot:</p>
<p><img src="images/Chapter9/lighting_finished.png" alt="image" /></p>
<p>Note that the preview of the lighting effects in <span>SpriteBuilder</span> currently don’t match the lighting effects on the simulator or device exactly. To get a good understanding of how your lighting effects are working you’ll need to run your game from <span>Xcode</span>.</p>
<p>Now all that’s left in terms of lighting is assigning normal maps to our falling objects as well!</p>
<p>[Testing lighting effects on the simulator] In case you’ve been curious and have tried running the current version of the project, you might have realized that the performance in the simulator is pretty poor. The reason is that the iOS simulator doesn’t use your computers GPU for all OpenGL features, but instead simulates many of them in software, which in many cases can be extremely slow. When working with CCEffects I recommend testing your game on an actual device if you have the required Apple Developer Account.</p>
<h3 id="assigning-normal-maps-in-code">Assigning Normal Maps in Code</h3>
<p>As mentioned earlier, the falling objects are spawned dynamically in code, therefore we cannot assign the normal maps in <span>SpriteBuilder</span>. However, adding normal maps in code is pretty simple. Additionally, we will need to look into adding the lighting effect to all falling objects in code, so that they are affected by our two light sources.</p>
<p>As you might remember, we had a clever way of managing the different assets for our falling objects. We are using a <em>plist</em> file that stores the image names for all <em>positive</em> and <em>negative</em> objects. The goal of this attempt is to keep information about game content outside of our codebase. In software design this principle is called <em>configuration over code</em>.</p>
<p>Ideally we want to use the same approach for the normal maps we are about to assign. We could simply add the image names of all the normal maps to the plist to accomplish that. However, there’s another interesting principle in software design: <em>convention over configuration</em>. When creating the normal maps for the sprites in our game, I have followed a <em>convention</em>. Each normal map file name is built as following: <em>{ImageName}_NRM.png</em></p>
<p>This means that we know the file name of the normal map as soon as we now the file name of the sprite’s texture. Using this knowledge, the implementation of setting up normal maps in code becomes pretty straightforward.</p>
<p>Open <span>FallingObject.swift</span> and extend the <span>init(type:)</span> initializer by adding the following lines <strong>to the end of the initializer</strong>:</p>
<pre><code>effect = CCEffectLighting()
    
let imageNameSplit = split(imageName!) { $0 == &quot;.&quot; }
let imageNameFirstPart = imageNameSplit[0]
let normalMapName = &quot;\(imageNameFirstPart)_NRM.png&quot;

normalMapSpriteFrame = CCSpriteFrame(imageNamed: normalMapName)</code></pre>
<p>By adding the code above to the initializer of <span>FallingObject</span>, we make sure that the lighting effect and the normal map are set up as soon as the object is created.</p>
<p>In the first line we set up the <span>CCEffectLighting</span> and assign it to the <span>effect</span> property of our <span>FallingObject</span>. The <span>effect</span> property is inherited from <span>CCSprite</span>. Now our falling object will be affected by light sources.</p>
<p>The remaining lines are used to assign the correct normal map to this object. We split the image name to get the part before the file extension. Then we append <em>_NRM.png</em> to that first part to retrieve the filename of the normal map. Within the closure passed to the <span>split</span> function we access a variable called <span>$0</span>. This is a cool feature in Swift, within closures we can access parameters either by name or by using the <span>$</span> symbol in combination with the index of the argument. Using these shorthand argument names is pretty common when working with standard library functions such as <span>split</span>, <span>map</span>, etc.</p>
<p>Finally, we use the generated filename for the normal map to load a <span>CCSpriteFrame</span> that we can assign to the <span>normalMapSpriteFrame</span>. That property is also inherited from <span>CCSprite</span>.</p>
<p>Now the falling objects are set up with the correct normal maps - but they still won’t be affected by the light sources. Remember: every <span>CCSprite</span> that wants to be affected by any kind of CCEffect needs to be a child of a CCEffectNode. Right now we are adding all falling objects directly to <span>MainScene</span>, which is a simple <span>CCNode</span>.</p>
<p>We will need to change our spawning code so that the objects get added to the CCEffectNode.</p>
<p>Before we can do that, we need a code connection for the effect node.</p>
<p>Add a code connection for the <span>CCEffectNode</span>:</p>
<ol>
<li><p>Open <em>MainScene.ccb</em></p></li>
<li><p>Select the <em>CCEffectNode</em> from the timeline</p></li>
<li><p>Open the code connections tab and create a connection to <em>Doc root var</em> named <em>effectNode</em></p></li>
<li><p>Publish the <span>SpriteBuilder</span> project</p></li>
</ol>
<p>Next, we need to set up a property for this code connection:</p>
<p>Add the following property to the <span>MainScene</span> class:</p>
<pre><code>weak var effectNode: CCEffectNode!</code></pre>
<p>And now we can update the spawn method to add all objects to the effect node.</p>
<p>Update the <span>spawnObject</span> method as shown below:</p>
<pre><code>func spawnObject() {
  ...
  
  // spawn all objects at top of screen and at a random x position within scene bounds
  let xSpawnRange = Int(contentSizeInPoints.width - CGRectGetMaxX(fallingObject.boundingBox()))
  let spawnPosition = ccp(CGFloat(randomInteger(xSpawnRange)), contentSizeInPoints.height)
  fallingObject.position = spawnPosition
  fallingObject.zOrder = DrawingOrder.GameplayElements.rawValue
  
  (*@\colorbox{light-gray}{effectNode.addChild(fallingObject)}@*)
}</code></pre>
<p>Now our falling objects are good to go! If you run this version of the game you should see detailed lighting effects and subtle reflections on all of the spawned objects.</p>
<p>This concludes our coverage of the <span>CCEffects</span> API for this book. You now know the basic set up that effects require. You also know how to configure effects in <span>SpriteBuilder</span> and in code. The lighting effect is one of the more complicated ones provided by the effects API - you should be able to pick up simpler effects such as <em>blur</em> and <em>saturation</em> pretty easily.</p>
<p>If you find some time, I highly recommend playing around with this API. With little time investment you will be able to create stunning visual effects.</p>
<h2 id="adding-particle-effects">Adding Particle Effects</h2>
<p>Another great way to improve the look and feel of your game is to add particle effects. Particle effects are used to animate huge amounts of very small sprites. That can be very useful when animating fire, smoke or explosions. Here’s an example of what a particle effect in <span>Cocos2D</span> can look like:</p>
<p><img src="images/Chapter9/particle_fire.png" alt="image" /></p>
<p><span>SpriteBuilder</span> comes with built in support for particle effects which makes it easy to create them and iterate on them while watching a live visual preview. For our game we will add a particle effect that takes place as soon as the player catches one of the good objects.</p>
<p>We are going to design the particle effect in <span>SpriteBuilder</span>, then load it and add it to the scene dynamically in code.</p>
<h3 id="creating-a-particle-effect-in-spritebuilder">Creating a Particle Effect in <span>SpriteBuilder</span></h3>
<p>Let’s open our <span>SpriteBuilder</span> project to get started!</p>
<p>Create a new <span>CCB File</span> of type <em>Particle</em> and call it <em>CaughtParticleEffect.ccb</em>:</p>
<p><img src="images/Chapter9/create_particle_effect.png" alt="image" /></p>
<p>Now you should see a new file with the default fire particle effect. For our game we want to create a different effect; something like a small colorful explosion.</p>
<p>To find out how we can create or our particle effect we need to understand their basic components.</p>
<p>There are two different aspects that make up a particle effect. The first is the texture for the individual particles, the second are all the settings that define how the particles of the system move, change over time, how long the entire particle systems lasts, etc. There are well over 20 settings that you can use to build your particle effects - discussing all of them goes well beyond the scope of this book.</p>
<p>There are two essentially different ways to start out building your own effect. You can start entirely from scratch, choosing your own particle texture and experimenting with the vast amount of available configuration options. Alternatively, you can select a particle effect from <span>SpriteBuilder</span>’s templates and modify it to build your custom effect.</p>
<p>In most cases this second approach makes more sense. You will likely be able to find an existing particle effect that is a good starting point for your custom one. For this game we will use that second approach and will use a very slightly modified library effect.</p>
<p>The best way to dive deeper into particle effects is spending some time playing around with the different options the editor in <span>SpriteBuilder</span> provides.</p>
<p>Let’s turn our fire effect into an explosion effect.</p>
<p>Select the <em>CCParticleSystem</em> in the timeline. Then open the last tab in the inspector panel on the right. Scroll down to the <em>Exploded Ring</em> effect and <strong>double-click</strong> onto it to select it:</p>
<p><img src="images/Chapter9/select_exploded_ring.png" alt="image" /></p>
<p>Now you should see the fire being replaced by an exploding ring. You will notice that this particle effect will only run once, then you will see a blank stage. That’s because this template creates an effect that has a limited lifetime.</p>
<p>The fire effect had a <em>duration</em> of <em>-1.0</em> seconds which indicates an endlessly looping effect. This effect has a <em>duration</em> of <em>0.01</em> seconds which means that particles are only emitted for a very short time.</p>
<p>If you want to start over watching the particle effect, you can click the <em>Start Particles</em> button in the inspector panel:</p>
<p><img src="images/Chapter9/start_particles.png" alt="image" /></p>
<p>The <em>duration</em> property defines the lifetime of the particle system, which defines how long particles will be created.</p>
<p>Each individual particle has a lifetime as well. In the exploded ring template the lifetime is set to <em>1.0</em> seconds. The larger this value, the longer the particles stay visible as the move from the center to the edge of the stage. This makes the ring appear larger.</p>
<p>We actually want the ring to be a little bit smaller so that the particles dissolve within the pot. Later we will add it to the inside of the pot as soon as an object is caught. We want it to look like all the particles are contained inside of the pot. After playing around with a few values I settled with <em>0.6</em> for the lifetime variance of each particle.</p>
<p>Change the <em>variance</em> <em>Life</em> property of this effect in the inspector panel to <em>0.6</em>:</p>
<p><img src="images/Chapter9/change_lifetime.png" alt="image" /></p>
<p>When you start this particle effect again, you will see that the explosion circle now appears smaller. Note that we are defining a <em>range</em> for the lifetime of each particle. In our case that’s between <em>0.0</em> and <em>0.6</em> seconds. The actual lifetime of each individual particle is some random value within this rage. This makes the particle effect appear more natural and less mechanic.</p>
<p>This completes our particle effect setup in <span>SpriteBuilder</span>. Feel free to spend some time exploring the other properties of particle effects before moving on!</p>
<p>Next, we’ll load this particle effect in code and add it to our game scene dynamically whenever the user catches a good object.</p>
<h3 id="loading-particle-effects-in-code">Loading Particle Effects in Code</h3>
<p>Now it’s time to pull up the <span>Xcode</span> project again. We want to run the particle effect when the player catches a good object. This means we need to extend the <span>performCaughtStep</span> method that we implemented earlier.</p>
<p>We’ll first load the <span>CCB File</span> that stores the particle effect, then we’ll position it and add it to the top part of the pot. We will position the effect so that it takes place inside of the body of the pot.</p>
<p>The particle effect starts automatically as soon as it is added to a visible scene. Unlike animations we don’t need to start them manually.</p>
<p>Let’s implement this feature and then discuss some more details!</p>
<p>Extend the implementation of <span>performCaughtStep(fallingObject:)</span> to load and add the particle effect:</p>
<pre><code>func performCaughtStep(fallingObject:FallingObject) {
  // if the object was caught, remove it as soon as soon as it is entirely contained in the pot
  if (CGRectContainsRect(pot.catchContainer.boundingBox(), fallingObject.boundingBox())) {
    gameMode?.gameplay(self, caughtFallingObject: fallingObject)
    fallingObject.removeFromParent()
    let fallingObjectIndex = find(fallingObjects, fallingObject)!
    fallingObjects.removeAtIndex(fallingObjectIndex)
    
    (*@\colorbox{light-gray}{// New code starts here}@*)
    if (fallingObject.type == .Good) {
      let particleEffect = CCBReader.load(&quot;CaughtParticleEffect&quot;) as! CCParticleSystem
      particleEffect.autoRemoveOnFinish = true
      particleEffect.positionType = CCPositionType(
        xUnit: .Normalized,
        yUnit: .Points,
        corner: .TopLeft
      )
      particleEffect.position = ccp(0.5, 20)
      pot.potTop.addChild(particleEffect)
    }
  }
}</code></pre>
<p>Let’s look at the code we added, step by step. First, we check the object type. We want to display the particle effect only if the user caught a <span>.Good</span> object. If that’s the case, we use the <span>CCBReader</span> to load the <span>CCB File</span> that contains the particle effect. We parse the value returned by the <span>CCBReader</span>.</p>
<p>Next, we configure an important setting on the particle effect. We set <span>autoRemoveOnFinish</span> to <span>true</span>. This means that <span>Cocos2D</span> will take care of removing this particle effect from its parent object as soon as the particle effect completes. A particle effect completes once all emitted particles have reached the end of their lifetime. Without this line of code you would need keep track of all added particle effects manually and make sure to remove them - an easy way to introduce memory issues into your game.</p>
<p>With the particle loaded and set up, we take care of positioning it. This particle effect should be rendered inside of the pot’s body. I’ve decided to center the effect horizontally. We set up a position type that makes the centering easy and that allows us to position the particle effect from the top edge of the pot instead of from the bottom.</p>
<p>Then we set the position: horizontally centered, vertically slightly below the top edge of the pot.</p>
<p>In the last step we add the <span>particleEffect</span> to <span>potTop</span>.</p>
<p>[An alternative positioning approach] Instead of setting the position type and the position of the particle system in code, you could also add an empty node in <span>SpriteBuilder</span> at the position where you want to render the particle effect. Then you could add the particle effect to that node instead of to <span>potTop</span>. I tend to use this approach for positions that are harder to express in code.</p>
<p>Now you can run the game. You’ll see the particle effect run as soon as you catch a good object.</p>
<p>This game is already looking a lot more polished than at the beginning of this chapter.</p>
<p>In the next and last section we will look into using the <span>SpriteBuilder</span> timeline to add some more animations to our core gameplay.</p>
<h2 id="delightful-animations-with-spritebuilders-timeline">Delightful Animations with <span>SpriteBuilder</span>’s timeline</h2>
<p>We will now add some animations to the game to wrap this chapter up. So far we’ve used the <span>SpriteBuilder</span> timeline to animate user interfaces, now we want to animate parts of our gameplay as well.</p>
<p>Whenever the player catches a good object we’ll let the pot play a little wobble animation:</p>
<p><img src="images/Chapter9/wobble_animation.png" alt="image" /></p>
<p>Later on we will create a second animation, based on this one, where we add a coloring effect that turns the pot red. We will use that second animation whenever the user catches a bad object.</p>
<p>Let’s get started on creating these animations! You might remember that the top and the bottom part of the pot need to have the same parent node as the falling object due to a limitation in <span>Cocos2D</span>. This means we cannot group them under a container node. We discussed this in detail in chapter [rendering<sub>t</sub>weak] (<em>A rendering tweak</em>). This unfortunately means that we need to copy the keyframes for the animation for both parts of the pot. Luckily <span>SpriteBuilder</span> makes this pretty easy!</p>
<p>Open up the <span>SpriteBuilder</span> project and select the <span>Pot.ccb</span> file.</p>
<ol>
<li><p>Create a new timeline :</p>
<p><img src="images/Chapter9/timeline_new.png" alt="image" /></p></li>
<li><p>Name that timeline <em>CatchAnimation</em> (if you don’t remember how to rename timelines you can jump back to chapter [timeline<sub>r</sub>ename])</p></li>
<li><p>Zoom in all the way in the timeline since the animation we’re building will be very short:</p>
<p><img src="images/Chapter9/zoom_timeline.png" alt="image" /></p></li>
<li><p><strong>Make sure you have selected the <em>CatchAnimation</em> timeline</strong></p></li>
<li><p>Select the <strong>pot-bottom</strong> node from the timeline</p></li>
<li><p>Create rotation keyframes at with the following frame and rotation values:</p>
<ol>
<li><p>frame: 00:00:00, rotation: 0</p></li>
<li><p>frame: 00:00:03, rotation: 10</p></li>
<li><p>frame: 00:00:05, rotation: 0</p></li>
<li><p>frame: 00:00:07, rotation: -10</p></li>
<li><p>frame: 00:00:10, rotation: 0</p></li>
</ol>
<p>The result should look as following:</p>
<p><img src="images/Chapter9/wobble_timeline.png" alt="image" /></p></li>
</ol>
<p>Great, you should be able to play this animation and see the bottom part of the pot wobbling. Once you are up to speed with <span>SpriteBuilder</span>’s timeline, building animations becomes extremely fast!</p>
<p>Next, we need to copy this animation for the top part of the pot.</p>
<p>Let’s copy the keyframes we just created and add them to <strong>pot-top</strong>:</p>
<ol>
<li><p>Hold down the Shift key and click onto each of the 5 keyframes</p></li>
<li><p>Use the <em>CMD + C</em> shortkey to copy the keyframes</p></li>
<li><p>Select the <strong>pot-top</strong> node from the timeline. Drag the timeline ruler all the way to the left, to frame 0 (the copied keyframes will be added at the position of the ruler). Then use the <em>CMD + V</em> shortkey to paste the keyframes:</p>
<p><img src="images/Chapter9/copy_keyframes.png" alt="image" /></p></li>
</ol>
<p>Now we’re done with the catch animation. You can use the timeline playback tool to preview the animation.</p>
<p>Before we switch to <span>Xcode</span> to write code that will play this timeline, let’s add the animation for catching negative objects as well.</p>
<p>Essentially all we need to do is copy the entire animation that we’ve created so far and add an animation to fade the color of the pot to red.</p>
<p>Let’s create the second timeline with the animation for catching negative objects.</p>
<ol>
<li><p>Open <em>Pot.cbb</em></p></li>
<li><p>Create a new timeline</p></li>
<li><p>Name the timeline <em>CatchNegativeAnimation</em></p></li>
<li><p>Switch to the <em>CatchAnimation</em> timeline</p></li>
<li><p>Copy the 5 keyframes from the wobble animation from the <em>CatchAnimation</em> timeline by selecting all keyframes with the <em>Shift</em> key and then using the <em>CMD + C</em> shortkey</p></li>
<li><p>Switch back to the <em>CatchNegativeAnimation</em> timeline</p></li>
<li><p>Select the <strong>pot-top</strong> node from the timeline</p></li>
<li><p>Make sure the timeline ruler is at frame 0</p></li>
<li><p>Use the <em>CMD + V</em> keys to paste the animation</p></li>
<li><p>Select the <strong>pot-bottom</strong> node from the timeline</p></li>
<li><p>Use the <em>CMD + V</em> keys to paste the animation</p></li>
</ol>
<p>Now it’s time to add the color fade animation that colors our pot red! This animation will not be a linear one. In chapter [timeline<sub>i</sub>nterpolation] we discussed that <span>Cocos2D</span> provides different types of interpolations for our animations. I’ve built the color animation using the <em>Ease Out</em> / <em>Ease In</em> interpolations. That makes the color snap to red pretty fast, and then fade out to white a little bit slower. Choosing different interpolations every once in a while, instead of always using the default linear interpolation, will make your animations look more interesting.</p>
<p>Make sure you have the <em>CatchNegativeAnimation</em> timeline selected before starting!</p>
<ol>
<li><p>Select the <strong>pot-bottom</strong> node from the timeline</p></li>
<li><p>Add the following <em>Color</em> keyframes:</p>
<ol>
<li><p>frame: 00:00:00, color: white</p></li>
<li><p>frame: 00:00:05, color: red</p></li>
<li><p>frame: 00:00:10, color: white</p></li>
</ol></li>
<li><p><em>Right-Click</em> onto the pink bar between the first and the second keyframe</p></li>
<li><p>Select <em>Ease Out</em> from the context menu</p></li>
<li><p><em>Right-Click</em> onto the pink bar between the second and the third keyframe</p></li>
<li><p>Select <em>Ease In</em> from the context menu</p></li>
</ol>
<p>And now, as a very last step, we need to copy the animation from <strong>pot-bottom</strong> to <strong>pot-top</strong>.</p>
<p>Make sure you have the <em>CatchNegativeAnimation</em> timeline selected.</p>
<ol>
<li><p>Select the <strong>pot-bottom</strong> node from the timeline</p></li>
<li><p>Copy the three keyframes from the color animation</p></li>
<li><p>Set the timeline ruler to frame 0</p></li>
<li><p>Select the <strong>pot-top</strong> node from the timeline</p></li>
<li><p>Paste the three keyframes from the color animation</p></li>
</ol>
<p>And now we are all set! You should be a little bit more experienced at using the timeline at this point, and we have two new animations that will make our game look better.</p>
<p>Now, the final step for this chapter is adding code that will trigger the playback of our new timelines.</p>
<p>Publish the <span>SpriteBuilder</span> project!</p>
<h3 id="playing-the-timelines">Playing the Timelines</h3>
<p>Now it’s time to switch back to our <span>Xcode</span> project. Since both animations will be playing once an object is caught, we once again need to extend the <span>performCaughtStep(fallingObject:)</span> method in <span>MainScene.swift</span>.</p>
<p>We simply need to add two lines that trigger the timeline playback:</p>
<p>Extend the <span>performCaughtStep</span> method to look as following:</p>
<pre><code>func performCaughtStep(fallingObject:FallingObject) {
  // if the object was caught, remove it as soon as soon as it is entirely contained in the pot
  if (CGRectContainsRect(pot.catchContainer.boundingBox(), fallingObject.boundingBox())) {
    gameMode?.gameplay(self, caughtFallingObject: fallingObject)
    fallingObject.removeFromParent()
    let fallingObjectIndex = find(fallingObjects, fallingObject)!
    fallingObjects.removeAtIndex(fallingObjectIndex)
    
    if (fallingObject.type == .Good) {
      let particleEffect = CCBReader.load(&quot;CaughtParticleEffect&quot;) as! CCParticleSystem
      particleEffect.autoRemoveOnFinish = true
      particleEffect.positionType = CCPositionType(
        xUnit: .Normalized,
        yUnit: .Points,
        corner: .TopLeft
      )
      particleEffect.position = ccp(0.5, 20)
      pot.potTop.addChild(particleEffect)
      (*@\colorbox{light-gray}{// New code starts here}@*)
      pot.animationManager.runAnimationsForSequenceNamed(&quot;CatchAnimation&quot;, tweenDuration: 0.1)
    } else if (fallingObject.type == .Bad) {
      pot.animationManager.runAnimationsForSequenceNamed(&quot;CatchNegativeAnimation&quot;, tweenDuration: 0.1)
    }
  }
}</code></pre>
<p>If the player catches a good object, we play <em>CatchAnimation</em>, if the player catches a bad object we play <em>CatchNegativeAnimation</em>.</p>
<p>You might have noticed the new <span>tweenDuration</span> argument that we are using as part of calling <span>runAnimationsForSequenceNamed</span>. This duration defines how much time is used to animate a transition between two different timelines.</p>
<p>Since multiple objects can be caught in a very small timeframe, it could happen that the player catches a good object and then catches a bad object immediately afterwards. This might mean that the <em>CatchNegativeAnimation</em> would be started before the <em>CatchAnimation</em> can complete. If we wouldn’t use a <span>tweenDuration</span>, then the transition would happen instantly, which can result in noticeable jumps of the rotation and the blend color. Using a <span>tweenDuration</span>, <span>Cocos2D</span> generates a smooth transition between the timelines by animating the properties that need to be changed, instead of changing them instantly.</p>
<h2 id="summary-6">Summary</h2>
<p>In this chapter we have focused on polishing the gameplay by adding effects and animations. You have learned how to use the CCEffects API to inlcude lighting effects. You now know how normal maps can add a 3D feel to a 2D game. We have also added a particle effect to our game; hopefully you have seen that they are pretty easy to create and can be a great visual enhancement for your game. Lastly we have utilized the <span>SpriteBuilder</span> timeline to animate some aspects of our core gameplay. Getting up to speed with the timeline feature is extremely valuable - you will add great animations to your games in no time.</p>
<p>This chapter almost concludes this book! Thanks a lot for following through and building this entire project.</p>
<p>In the next and last chapter I will point you to some additional resources beyond this book.</p>
<h1 id="where-to-go-from-here">Where to Go from Here?</h1>
<p>After completing this entire book you should have a very good understanding of the essential features of <span>SpriteBuilder</span> and <span>Cocos2D</span>. However, each type of game has its own challenges. Additional books and tutorials will help you understand the structure of different types of games.</p>
<p>Note that all of the resources listed here are written in the Objective-C language. This book is (to my knowledge) currently the only book that uses Swift.</p>
<h2 id="building-games-with-the-physics-engine">Building Games with the Physics Engine</h2>
<p>There two different resources I would recommend:</p>
<dl>
<dt>Make School’s Peeved Penguins Tutorial</dt>
<dd><p>This tutorial provides an introduction to <span>SpriteBuilder</span> by cloning the popular game <em>Angry Birds</em>. It uses the physics engine to build the game. Link: <a href="https://www.makeschool.com/tutorials/getting-started-with-spritebuilder/" class="uri">https://www.makeschool.com/tutorials/getting-started-with-spritebuilder/</a></p>
</dd>
<dt>Learn SpriteBuilder Book</dt>
<dd><p>This is another book that focuses on <span>SpriteBuilder</span>. However, it uses a physics based game throughout the entire book. Link: <a href="http://www.apress.com/9781484202630" class="uri">http://www.apress.com/9781484202630</a></p>
</dd>
</dl>
<h2 id="building-puzzle-games">Building Puzzle Games</h2>
<dl>
<dt>Make School’s 2048 Tutorial</dt>
<dd><p>If you are interested in using <span>SpriteBuilder</span> and <span>Cocos2D</span> to build a puzzle game, you should check out Make School’s 2048 tutorial. Link: <a href="https://www.makeschool.com/tutorials/build-your-own-2048-with-spritebuilder-and-cocos2d/part-1" class="uri">https://www.makeschool.com/tutorials/build-your-own-2048-with-spritebuilder-and-cocos2d/part-1</a></p>
</dd>
</dl>
<h2 id="getting-help">Getting Help</h2>
<dl>
<dt>SpriteBuilder forum</dt>
<dd><p>Folks on the <span>SpriteBuilder</span> forum have been extremely helpful in the past. If you get stuck during a tutorial or while building your own game, you should ask for help there. Link: <a href="https://forum.spritebuilder.com" class="uri">https://forum.spritebuilder.com</a></p>
</dd>
</dl>
<h2 id="build-your-own-game">Build your own Game!</h2>
<p>I hope this book has helped you to learn enough about <span>SpriteBuilder</span> and <span>Cocos2D</span> to get started on your own game. If you finish a project, I would love to hear from you at: <em>me@benjamin-encz.de</em>!</p>