Influencing the Draw Order

Order of addChild

The simplest case is when you have a parent node to which you add several child nodes.

Let's assume these nodes are labels and the first label displays the letter A, the next displays B and so on. We name the variables referencing each label labelA, labelB and so forth. They all use the same position and same other properties. Most notably they all have the same zOrder property because we leave it at the default value of 0. Then the labels are added as children in ascending order, like so:

[self addChild:labelA];
[self addChild:labelB];
[self addChild:labelC];
[self addChild:labelD];
[self addChild:labelE];

Which one will be the topmost label? You may have guessed it: it's label E. Label E is added last, and therefore drawn last. Label A is drawn first.

zOrder Property

You have two options to change the draw order: change the order in which the labels are added, or change their zOrder property. When adding child nodes it is convenient to use the z parameter of the addChild method, like so:

[self addChild:labelA z:3];
[self addChild:labelB z:-4];
[self addChild:labelC z:7];
[self addChild:labelD z:-14];
[self addChild:labelE];

What's the draw order now? The answer is:

• labelD (zOrder = -14)

• labelB (zOrder = -4)

• labelE (zOrder = 0)

• labelA (zOrder = 3)

• labelC (zOrder = 7)

Label C is drawn last and is now the topmost label. As you can see, cocos2d draws nodes in ascending order, starting with the child node with the lowest zOrder property. The node with the highest zOrder property is drawn last. If two or more nodes have the same zOrder value, then the order in which they were added as child nodes comes into play again.

Draw Order in Relation to Parent

We have yet to consider the child node's parent in this example. What if the parent node is a sprite, how does that affect the draw order?

Cocos2D first renders all child nodes with a negative zOrder value. Then it renders the parent node and then goes on to render the child nodes with a zero or higher zOrder property. In general terms this is what happens every frame:

• draw child nodes with zOrder < 0

• draw parent node

• draw child nodes with zOrder >= 0

Going back to the above example, this is where the parent sprite will be sorted in the draw order list:

• labelD (zOrder = -14)

• labelB (zOrder = -4)

• parent sprite

• labelE (zOrder = 0)

• labelA (zOrder = 3)

• labelC (zOrder = 7)

Place in Scene Graph

Now you might think that you could change the zOrder of the parent to 10 in order to draw it in front of label C. Nope, it doesn't work this way.

The draw order of children is always relative to their parent. Meaning child nodes with positive zOrder will always be drawn on top of the parent, no matter what the parent's zOrder value is. Because the zOrder of the parent only affects the draw order of nodes in the same level as the parent.

To extend on the above you have to consider that every parent may have a parent of its own, and every child node may have additional child nodes. This is the node hierarchy. Cocos2D traverses that hierarchy and at each level of the hierarchy it renders the children and grandchildren based on their zOrder values. It's time for an illustration and a little brain flexing. Can you determine the correct draw order from sprite A through T?

Let's walk through it. The scene node doesn't matter since it doesn't draw anything - unless you add custom drawing (see Custom Drawing with OpenGL ES) at which point it would be drawn after sprite A and before sprite B. But leaving that out for a second, here's a rundown of what happens:

• sprite A has children with negative zOrder values

• cocos2d checks sprite A child nodes

• sprite D has lowest zOrder, and no children: draw sprite D

• next is Sprite E, it has children but they all have zOrder >= 0: draws sprite E

• cocos2d then draws sprite E's child nodes: draw sprite L and then sprite M

• cocos2d checks sprite F, it has children but they're all zOrder >= 0: draw sprite F

• check sprite N, it has children with negative zOrder: draw P, Q, R in the order they were added

• draws sprite N

• draws sprite O

• ...

Can you figure out the rest? Don't get mislead by the vertical order of the nodes in the image.

Here's the solution: D, E, L, M, F, P, Q, R, N, O, G, CCScene, B, H, I, J, S, T, C, K

The sprite C branch deserves an extra explanation. The order is J, S, T, C, K which stems from the fact that cocos2d first visits the negative zOrder children of sprite C. In sprite C it then finds no negative zOrder children and renders sprite J, but then it renders J's positive zOrder children S and T. Then it has finished traversing the JST branch and recurses back to sprite C where it determines there are no more negative zOrder children in C, so it draws sprite C. It then moves on to the positive zOrder children and draws sprite K last.

Long story short: with zOrder you can influence the draw order of nodes at the same level and relative to their parent. But you can not use the zOrder property to change the draw order of nodes which have different parents, ie nodes that live in different parts of the node hierarchy. For example sprite N and O are drawn in front of sprite L and M even though they have a lower zOrder. Sprites N and O are of course children of a parent with a higher zOrder (-5) than the parent E (-10) of which sprite L and M are children of.

Draw Order with Depth Buffering Enabled and Using vertexZ

Now while this zOrder and order of adding children business is pretty convenient and relatively straightforward once you start using it, there are cases where greater flexibility is important. In particular in games where you need to change the zOrder of nodes every frame. Usually these are games with an isometric perspective, where nodes with greater y coordinate are supposed to be drawn behind the nodes with a lower y coordinate.

Enter vertexZ and depth buffering. With depth buffering enabled, you can use the vertexZ property of a node to change it's OpenGL depth value. This vertexZ value allows you to change the draw order of nodes across the board, so a node with vertexZ of 10 will be drawn in front of all nodes with a vertexZ of 9 or lower - regardless of where these nodes are in the hierarchy.

To use vertexZ you must first enable depth buffering in CCGLView. To do this open AppDelegate.m and find where the CCGLView is initialized. Kobold2D users should make that change in the config.lua file instead.

CCGLView *glView = [CCGLView viewWithFrame:[window_ bounds]
                               pixelFormat:kEAGLColorFormatRGB565
                               depthFormat:GL_DEPTH_COMPONENT24_OES
                        preserveBackbuffer:NO
                                sharegroup:nil
                             multiSampling:NO
                           numberOfSamples:0];

Change the depthFormat parameter from 0 to GL_DEPTH_COMPONENT24_OES to enable the 24-Bit z buffer. The GL_DEPTH_COMPONENT16_OES constant for 16-Bit z buffers is no longer available in OpenGL ES 2.0.

Now you can start changing the vertexZ property of your nodes and observe the effect:

labelA.vertexZ = -10;
labelB.vertexZ = 40;
labelC.vertexZ = 0;
labelD.vertexZ = -1;
labelE.vertexZ = -50;