Tutorial: The Cocos2d Coordinate System

In order to successfully place and manipulate objects/images in Cocos2d, you have to understand its coordinate system.

Before we get into more details, here are some things you could know:

• Origin (System) — The origin (0,0) of the coordinate system is the lower-left corner of the application’s screen
• Origin (Sprite) — The origin of a sprite (image) is the lower-left corner of the image
• Anchor Point (Sprite) — A sprite’s anchor point (where it is drawn from) is the center of the image
• Relative Positioning — A sprite’s origin is relative to its parent’s origin

Origin (System)

The origin of the Cocos2d coordinate system is always the lower-left corner. It cannot be changed.

The x-axis increases as you move to the right of the screen.

The y-axis increases as you move up the screen.

Origin (Sprites)

A sprite’s origin is its lower-left corner, just like with the application itself. It cannot be changed.

Anchor Point (Sprites)

An anchor point dictates how a sprite is drawn on the screen. By default, the anchor point is in the center of the image. When change the position of an object, you are actually saying, “I want the object redrawn with its anchor point at location (x,y).”

Example: A 6×6 pixel square positioned at (4,4) will be centered at (4,4) and have its corners at (1,1), (1,7), (7,1), (7,7).

However, unlike the origin of a sprite, you can change the anchor point using the following code:
spriteName->setAnchorPoint(Vec2(xI, yI));

The setAnchorPoint() function takes two values: (xI,yI). These values can range from 0 to 1. The pair (0,0) represents the lower-left corner of the image and the pair (1,1) represents the upper-right corner or the image. The pair (0.5,0.5) represents the center of the image.

Once you change the anchor point, the sprite will be positioned on the screen based on that point.

Choosing an Anchor Point

Although (0,0), (1,1), and (0.5,0.5) are the most common anchor points, it is conceivable to choose a point anywhere in your image. The math for determine the correct xI and yI is as follows:

w = width of sprite
h = height of sprite

x_w = desired x-location of anchor point (in pixels) starting from the lower-left corner

y_h = desired y-location of anchor point (in pixels) starting from the lower-left corner

xI = x_1 / w
yI = y_h / h

Relative Positioning

When a sprite is created, it should be assigned a parent using the following code:
parentName->addChild(spriteName);

Usually, that parent is a layer. Since layers cover an application’s entire screen, positioning a sprite within a layer is very easy — just set its anchor point to the (x,y) coordinate you desire using:
spriteName->setPosition(x,y);

However, parents can also be other sprites/objects. If that happens, the sprite is assigned its position based on its parent’s origin, not the application’s. That means if the parent object is later moved around, your (child) sprite will move, too!