A Scene’s Size Defines Its Visible Area

When a scene is first initialized, its size property is configured by the designated initializer. The size of the scene specifies the size of the visible portion of the scene in points. This is only used to specify the visible portion of the scene. Nodes in the tree can be positioned outside of this area; those nodes are still processed by the scene, but are ignored by the renderer.

Using the Anchor Point to Position the Scene’s Coordinate System in the View

By default, a scene’s origin is placed in the lower-left corner of the view, as shown in Figure 4-3. So, a scene is initialized with a height of 1024 and a width of 768, has the origin (0,0) in the lower-left corner, and the (1024,768) coordinate in the upper-right corner. The frame property holds (0,0)-(1024,768).

A scene’s position property is ignored by Scene Kit because the scene is always the root node for a node tree. Its default value is CGPointZero and you can’t change it. However, you can move the scene’s origin by setting its anchorPoint property. The anchor point is specified in the unit coordinate space and chooses a point in the enclosing view.

The default value for the anchor point is CGPointZero, which places it at the lower-left corner. The scene’s visible coordinate space is (0,0) to (width,height). The default anchor point is most useful for games that do not scroll a scene’s content.

The second-most common anchor point value is (0.5,0.5), which centers the scene’s origin in the middle of the view as shown in Figure 4-4. The scene’s visible coordinate space is (-width/2,-height/2) to (width/2, height/2). Centering the scene on its anchor point is most useful when you want to easily position nodes relative to the center of the screen, such as in a scrolling game.

So, to summarize, the anchorPoint and size properties are used to compute the scene’s frame, which holds the visible portion of the scene.

A Scene’s Contents Are Scaled to Fit the View

After a scene is rendered, its contents are copied into the presenting view. If the view and the scene are the same size, then the content can be directly copied into the view. If the two differ, then the scene is scaled to fit in the view. The scaleMode property determines how the content is scaled.

When you design your game, you should decide on a strategy for handling the scene’s size and scaleMode properties. Here are the most common strategies:

• Instantiate the scene with a constant size and never change it. Pick a scaling mode that lets the view scale the scene’s content. This gives the scene a predictable coordinate system and frame. You can then base your art assets and gameplay logic on this coordinate system.

• Adjust the size of the scene in your game. Where necessary, adjust your game logic and art assets to match the scene’s size.

• Set the scaleMode property to SKSceneScaleModeResizeFill. SpriteKit automatically resizes the scene so that it always matches the view’s size. Where necessary, adjust your game logic and art assets to match the scene’s size.

Listing 4-1 shows a typical implementation for when you plan to use a constant-sized scene. As with the example you created in Jumping into SpriteKit, this code specifies a method to be executed the first time that the scene is presented. It configures the scene’s properties, including its scaling mode, then adds content. In this example, the scale mode is set to SKSceneScaleModeAspectFit, which scales the contents equally in both dimensions and ensures that all of the scene’s contents are visible. Where necessary, this mode adds letterboxing.

Listing 4-1  Using the scale mode for a fixed-size scene

- (void)createSceneContent

{

    self.scaleMode = SKSceneScaleModeAspectFit;

    self.backgroundColor = [SKColor blackColor];

// Add additional scene contents here.

...

}

If you expect a scene’s size to change at runtime, then the initial scene size should be used to determine which art assets to use, as well as any game logic that is dependent on the scene size. Your game should also override the scene’s didChangeSize: method, which is called whenever the scene changes size. When this method is called, you should update the scene’s contents to match the new size.

Understanding the Drawing Order for a Node Tree

The standard behavior for scene rendering follows a simple pair of rules:

• A parent draws its content before rendering its children.

• Children are rendered in the order in which they appear in the child array.

Figure 4-5 shows how a node with four children are rendered.

In the code you wrote in Jumping into SpriteKit, you created a scene with a spaceship and rocks. Two lights were specified as children of the spaceship, and the spaceship and rocks were the scene’s children. So the scene rendered its content as follows:

1. The scene renders itself, clearing its contents to its background color.

2. The scene renders the spaceship node.

3. The spaceship node renders its children, which are the lights on the spaceship.

4. The scene renders the rock nodes, which appear after the spaceship node in the scene’s array of children.

Maintaining the order of a node’s children can be a lot of work. Instead, you can give each node an explicit height in the scene. You do this by setting a node’s zPosition property. The z position is the node’s height relative to its parent node, much as a node’s position property represents its x and y position relative to parent’s position. So you use the z position to place a node above or below the parent’s position.

When you take z positions into account, here is how the node tree is rendered:

• Each node’s global z position is calculated.

• Nodes are drawn in order from smallest z value to largest z value.

• If two nodes share the same z value, ancestors are rendered first, and siblings are rendered in child order.

As you’ve just seen, SpriteKit uses a deterministic rendering order based on the height nodes and their positions in the node tree. But, because the rendering order is so deterministic, SpriteKit may be unable to apply some rendering optimizations that it might otherwise apply. For example, it might be better if SpriteKit could gather all of the nodes that share the same texture and drawing mode and and draw them with a single drawing pass. To enable these sorts of optimizations, you set the view’s ignoresSiblingOrder property to YES.

When you ignore sibling order, SpriteKit uses the graphics hardware to render the nodes so that they appear sorted by z order. It sorts nodes into a drawing order that reduces the number of draw calls needed to render the scene. But with this optimized drawing order, you cannot predict the rendering order for nodes that share the same height. The rendering order may change each time a new frame is rendered. In many cases, the drawing order of these nodes is not important. For example, if the nodes are at the same height but do not overlap on screen, they can be drawn in any order.

Figure 4-6 shows an example of a tree that uses z positions to determine the rendering order. In this example, the body of the helicopter is at a height of 100, and its children are rendered relative to its height. The two rotor nodes share the same height but do not overlap.

To summarize, you can use both tree order and z positions to determine your scene’s rendering order. When rendering a complex scene, you should disable the sorting behavior and use the z positions of nodes to create a deterministic scene order.

The Hit-Testing Order Is the Reverse of Drawing Order

In a scene, when SpriteKit processes touch or mouse events, it walks the scene to find the closest node that wants to accept the event. If that node doesn’t want the event, SpriteKit checks the next closest node, and so on. The order in which hit-testing is processed is essentially the reverse of drawing order.

For a node to be considered during hit-testing, its userInteractionEnabled property must be set to YES. The default value is NO for any node except a scene node. A node that wants to receive events needs to implement the appropriate responder methods from its parent class (UIResponder on iOS and NSResponder on OS X). This is one of the few places where you must implement platform-specific code in SpriteKit.

Sometimes, you also want to look for nodes directly, rather than relying on the standard event-handling mechanisms. In SpriteKit you can ask a node whether any of its descendants intersect a specific point in their coordinate system. Call the nodeAtPoint: method to find the first descendant that intersects the point, or use the nodesAtPoint: method to receive an array of all of the nodes that intersect the point.

Using a Node’s Depth to Add Other Effects

SpriteKit uses the zPosition value only to determine the hit testing and drawing order. You can also the z position to implement your own game effects. For example, you might use the height of a node to determine how it is rendered or how it moves onscreen. In this way, you can simulate fog or parallax effects. SpriteKit does not create these effects for you. Usually, you implement them by processing the scene immediately before it is rendered. See Advanced Scene Processing.