Mechanism of Loading Resources¶

• Mechanism of Loading Resources
  • 1. Distributed strategy
    • 1.1. Developer guilde
    • 1.2. Notes
  • 2. Centralized strategy
    • 2.1. Why use a different mechanism than cocos2d-iphone
    • 2.2. What is the new mechanism
    • 2.3. Developer guide
    • 2.5. Notes
  • Comment

There are two different mechanisms of loading resources since cocos2d-2.1beta3-x-2.1.1:

• distributed strategy
  This strategy is used in CocosBuilder. It put all retina resources into different directories. We will describe it in detail following.
• centralized strategy
  This strategy put all retina resources into a separate directory.

Don't use two strategies together. If your project is not created by CocosBuilder. I sugget you use centralized strategy. Just use CCFileUtils::setSearchPath() (setResourceDirectory is deprecated) to set searching paths.

1. Distributed strategy¶

This strategy is used in cocos2d-iphone and CocosBuilder. The resource directory looks like

As you can see, retina resources(a.png and b.png) are put into Resources/resources-iphonehd and Resources/image/resources-iphonehd.

1.1. Developer guilde¶

CCFileUtils::setSearchResolutionsOrder() is added to support distributed strategy. You can set searching resolutions order like this

1std::vector<std::string> resDirOrders;
2if (resolution is ipad retina)
3{
4    resDirOrders.push_back("resources-ipadhd");
5    resDirOrders.push_back("resources-ipad");
6    resDirOrders.push_back("resources-iphonehd");
7}
8CCFileUtils::sharedFileUtils()->setSearchResolutionsOrder(resDirOrders);

After setting searching resolutions order, suppose we create a sprite like this

1CCSprite *sprite = CCSprite::create("images/tex.png"); 

Engine will find tex.png in the following sequence

• find it in images/resources-ipadhd/
• if not found, find it in images/resources-ipad/
• if not found, find it in images/resources-iphonehd/
• if not found, find it in images/

1.2. Notes¶

This strategy is not suitable for multi-resolution adaption, because there are too many resolutions on Android. You can not provide all resources for all resolutions, then set searching order based on resolutions, such as

 1std::vector<std::string> resDirOrders;
 2if (resolution is reslution1)
 3{
 4    resDirOrders->push_back("path1");
 5    resDirOrders->push_back("path2");
 6    ...
 7}
 8else if (resolution is resolution2)
 9{
10    resDirOrders->push_back("path-a");
11    resDirOrders->push_back("path-b");
12    ...
13}
14...
15
16CCFileUtils::sharedFileUtils()->setSearchResolutionsOrder(resDirOrders);

2. Centralized strategy¶

2.1. Why use a different mechanism than cocos2d-iphone¶

Cocos2d-iphone uses -hd, -ipad, -ipadhd to determine which picture to load. This mechanism is good enough for iOS platform, but is not so suitable for Android, because it has many different resolutions. Cocos2d-x is a cross platform engine, so it should use another mechanism.

2.2. What is the new mechanism¶

Cocos2d-x uses the new mechanism to load a picture since version cocos2d-2.0-x-2.0.2. It does not use -hd, -ipad, -ipadhd suffixes to indicate images for different resolutions.
The mechanism is:
Try to find a picture in the paths set by CCFileUtils::setSearchPaths() firstly, if it's not found, then find the picture in Resources/

1// set searching paths to "/mnt/sd/example" and "/data/data/org.cocos2dx.example" 
2vector<string> searchPaths;
3searchPaths.push_back("/mnt/sd/example");
4searchPaths.push_back("/data/data/org.cocos2dx.example");
5CCFileUtils::setSearchPaths(searchPaths);  
6// engine will find "1.png" in /mnt/sd/example, if there it is not found, then engine will find "1.png" in /data/data/org.cocos2dx.example
7// if not found, engine will find "1.png" in Resources/ (this path is platform dependent)
8CCSprite *pSprite = CCSprite::create("1.png");  

It is easy to add searching path to engine. Using this method, you can load resources into a path you know, then set this path to engine. Engine will find a resource in this path if needed.

2.3. Developer guide¶

• Do not use -hd, -ipad, -ipadhd suffixes any more. Instead, put all hd files in a directory, then all ipad files in another directory, and so on, then set resource directory to tell the engine where to find a picture.
• If you want to share some resources between different resolutions, then you can put all shared resources in Resources/, and put resolution specified resources in different directories.

You can refer to samples/HelloCpp for more information.

2.4. For example:

• resources/
  • ipad/
    • background.png
  • iphone4/
    • background.png
  • sharedResource.png
• classes/

2.5. Notes¶

There are some things you should be noted about the new mechanism:

• Do not use -hd, -ipad & -ipadhd suffix as the "file" name field in .fnt file
• Do not use -hd, -ipad & -ipadhd suffix as the "textureFilename" name field in .plist file
• Do not use -hd, -ipad & -ipadhd suffix as the "image source" name field in .tmx file
• You should set shared resource's scale property to achieve the same display size on both Retina & Non-Retina devices, but particles are exceptional.
• Use centralized strategy as you can