5. Working with Multiple Resolutions
A common scenario when creating apps or games is to target multiple devices with different screen sizes. CocosBuilder provides advanced tools for supporting multiple resolutions and relative positioning. You can use the same file to have support for iPhone and iPad and a multitude of Android devices (if you are using cocos2d-x).
When creating a new file you select the resolutions that you want to support natively. Each resolution setting has a number of properties, such as width, height, resource extension and global scale.
CocosBuilder's resolution settings only reflects what is displayed in CocosBuilder, and are not exported to your ccbi-files. However, the default settings in CocosBuilder corresponds to the default settings in cocos2d. If you make changes to the default settings, please be aware that you may also need to make corresponding changes in your code when loading the file.
If you need to edit the resolutions after a document has been created you can do so by selecting Edit Resolutions… in the View menu.
An important aspect of getting the multiple resolution support to work satisfactory is to select the correct resources for the correct display. The Resource extension determines which resources are selected for a particular resolution. For instance, for the ipad hd setting the resources with the -ipad extension are selected first hand, if no such resource is found resources with the -hd extension is used. If none of the listed extensions are found for a particular resource, the fallback is the resource without an extension. You place all your images, with the different resolution extensions, in a directory within your projects resource path.
The project view will only list resources without a resolution extension. Resources with an extension are hidden.
CocosBuilder works entirely with points and not pixels. This means that you will only be seeing non-retina display layouts inside CocosBuilder. When you load the ccbi-files in cocos2d, cocos2d will select the -hd or -ipadhd (for retina iPad) resources. This is the reason why you won't have the option to select -ipadhd as an extension when editing your resolution settings.
By default cocos2d only supports absolute sizes for setting the contentSize of a node. Included with CCBReader is an extension which allows setting the contentSize relatively to the nodes parent. (If you want to use this feature programmatically, include the CCNode+CCBRelativePositioning.h file.)
There are six different options for setting the size of a node in CocosBuilder:
- Absolute: This sets the size to an absolute value (in points).
- Percentage of container size: This sets the content size to a percentage of its parents content size. If it is the root node of the ccb-file it will (by default) be a percentage of the devices screen size.
- Relative container size: This option will calculate the nodes content size by subtracting the width/height values that you enter with the width/height value of the parent node. It can also be seen as an inset of the parents content size.
- Horizontal percentage of container, fixed height: The width is set as a percentage, while the height is absolute (points).
- Vertical percentage of container, fixed width: The height is set as a percentage, while the width is absolute (points).
- Multiply by resolution scale: This option multiplies the value that you enter by the resolution scale factor which is specified for the current resolution.
All relative positioning in CocosBuilder is in relation to the position and content size of a nodes parent. In particular, if you are using the percentage option it will only work if the parent node has a size.
- Absolute: This sets the position to an absolute value (in points), same as cocos2d would normally use.
- Relative top-left: This sets the position relative to the top-left corner of the parent node.
- Relative top-right: This sets the position relative to the top-right corner of the parent node.
- Relative bottom-right: This sets the position relative to the bottom-right corner of the parent node.
- Percentage of container: Uses a percentage of the parent's content size to set the position relative to the bottom-right corner of the parent node. E.g. using the value 50,50 will place the node in the middle of its parent.
- Multiply by resolution scale: This option multiplies the value that you enter by the resolution scale factor which is specified for the current resolution.
You can use relative scaling for any object's scale or for some float based properties (e.g. the font size of CCLabelTTF).
- Absolute: CocosBuilder will use the scale you provide regardless of which resolution is currently used.
- Multiply by resolution scale: The value will be multiplied by the resolution scale factor for the current resolution.
The resolution sizes are not saved in the ccbi-files, by default the screen size is used as the parent size when the files are loaded. If you have used a custom size you may need to pass this size to the loader. To do this you will need to use the nodeGraphFromFile:owner:parentSize: or sceneWithNodeGraphFromFile:owner:parentSize: methods.
CGSize mySize = CGSizeMake(100.0f, 100.0f);
CCNode* myNode = [CCBReader nodeGraphFromFile:@"myNode.ccbi" owner:NULL parentSize:mySize];
Before loading your ccbi-files you can set the resolution scale you want to use. The default resolution scale is 1 for iPhone and 2 for iPad, but sometimes it can be useful to use other scale factors.
[CCBReader setResolutionScale: 2.5f];
- It is always better to design for multiple resolutions from the start in a project, rather then trying to convert an existing layout to fit different devices.
- If you are planning on using letter boxing, the multiply by resolution scale option can be very useful.
- Combine setting the anchor point of an object with the relative positioning options to pin nodes to corners or sides of the screen.
- You can achieve very complex behaviors for the multiple resolutions by nesting different positioning and size options.
- Don't be afraid to experiment with the different options, it can be complex at first sight, but once you get the hang of it you will have many options for laying out your scenes.