CCFileUtils Class Reference

Inherits from NSObject
Declared in CCFileUtils.h

Overview

Helper class to resolve files with resolution-specific suffixes (ie -hd) to actual file paths, including fallbacks.

Warning: CCFileUtils should no longer be used by developers! CCFileUtils will be deprecated in an upcoming Cocos2D version!

Consider CCFileUtils a private API and this documentation only for instructional purposes and “historical” reference. Unfortunately too many such references exist so that it would be a disservice to developers not to document the details of CCFileUtils, no matter how much we all ยง/%&“)$/$%! what CCFileUtils has grown into.

All the methods you shouldn't be using :)

  bundle

NSBundle used by CCFileUtils. By default it uses [NSBundle mainBundle].

@property (nonatomic, readwrite, strong) NSBundle *bundle

Discussion

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

  fileManager

NSFileManager used by CCFileUtils. By default it uses its own instance.

@property (nonatomic, readwrite, strong) NSFileManager *fileManager

Discussion

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

  enableiPhoneResourcesOniPad

Whether of not the fallback suffixes is enabled. When enabled it will try to search for the following suffixes in the following order until one is found: * On iPad HD : iPad HD, iPad, iPhone HD, Resources without resolution * On iPad : iPad, iPhone HD, Resources without resolution * On iPhone HD: iPhone HD, Resources without resolution * On Mac HD : Mac HD, Mac, Resources without resolution * On Mac : Mac, Resources without resolution

@property (nonatomic, readwrite, getter=isEnablediPhoneResourcesOniPad) BOOL enableiPhoneResourcesOniPad

Discussion

By default this functionality is on;

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

  directoriesDict

Dictionary that contians the search directories for the different devices. Default values: - iPhone: “resources-iphone” - iPhone HD: “resources-hd” - iPhone5 : “resources-wide” - iPhone5 HD: “resources-widehd” - iPad: “resources-ipad” - iPad HD: “resources-ipadhd” - Mac: “resources-mac” - Mac HD: “resources-machd”

@property (nonatomic, copy) NSMutableDictionary *directoriesDict

Discussion

If “search in directories” is enabled (disabled by default), it will try to get the resources from the directories according to the order of “searchResolutionsOrder” array.

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

  suffixesDict

Dictionary that contians the suffix for the different devices. Default values: - iPhone: “” - iPhone HD: “-hd” - iPhone5 : “-wide” - iPhone5 HD: “-widehd” - iPad: “-ipad” - iPad HD: “-ipadhd” - Mac: “” - Mac HD: “-machd”

@property (nonatomic, copy) NSMutableDictionary *suffixesDict

Discussion

If “search with suffixes” is enabled (enabled by default), it will try to get the resources by appending the suffixes according to the order of “searchResolutionsOrder” array.

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

  searchResolutionsOrder

Array that contains the search order of the resources based for the device. By default it will try to load resources in the following order until one is found: - On iPad HD: iPad HD resources, iPad resources, resources not associated with any device - On iPad: iPad resources, resources not associated with any device - On iPhone 5 HD: iPhone 5 HD resources, iPhone HD resouces, iPhone 5 resources, iPhone resources, resources not associated with any device - On iPhone HD: iPhone HD resources, iPhone resouces, resources not associated with any device - On iPhone: iPhone resources, resources not associated with any device

@property (nonatomic, strong) NSMutableArray *searchResolutionsOrder

Discussion

  • On Mac HD: Mac HD resources, Mac resources, resources not associated with any device
  • On Mac: Mac resources, resources not associated with any device

If the property “enableiPhoneResourcesOniPad” is enabled, it will also search for iPhone resources if you are in an iPad.

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

  searchPath

Array of search paths. You can use this array to modify the search path of the resources. If you want to use “themes” or search resources in the “cache”, you can do it easily by adding new entries in this array.

@property (nonatomic, copy) NSArray *searchPath

Discussion

By default it is an array with only the “” (empty string) element.

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

  searchMode

It determines how the “resolution resources” are to be searched. Possible values: - kCCFileUtilsSearchSuffix: It will search for resources by appending suffixes like “-hd”, “-ipad”, etc… - kCCFileUtilsSearchDirectory: It will search the resoureces in subdirectories like “resources-hd”, “resources-ipad”, etc…

@property (nonatomic, readwrite) CCFileUtilsSearchMode searchMode

Discussion

Default: kCCFileUtilsSearchSuffix

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

  filenameLookup

Dictionary used to lookup filenames based on a key. It is used internally by the following methods:

@property (nonatomic, readwrite, copy) NSMutableDictionary *filenameLookup

Discussion

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

– setiPhoneRetinaDisplaySuffix:

The iPhone RetinaDisplay suffixes to load resources. By default it is “-hd” and “” in that order. Only valid on iOS. Not valid for OS X.

- (void)setiPhoneRetinaDisplaySuffix:(NSString *)iPhoneRetinaDisplaySuffix

Parameters

iPhoneRetinaDisplaySuffix

Suffix to set

Discussion

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

– setiPadSuffix:

The iPad suffixes to load resources. By default it is “-ipad”, “-hd”, “”, in that order. Only valid on iOS. Not valid for OS X.

- (void)setiPadSuffix:(NSString *)iPadSuffix

Parameters

iPadSuffix

Suffix to set

Discussion

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

– setiPadRetinaDisplaySuffix:

Sets the iPad Retina Display suffixes to load resources. By default it is “-ipadhd”, “-ipad”, “-hd”, “”, in that order. Only valid on iOS. Not valid for OS X.

- (void)setiPadRetinaDisplaySuffix:(NSString *)iPadRetinaDisplaySuffix

Parameters

iPadRetinaDisplaySuffix

Suffix to set

Discussion

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

– setiPhoneContentScaleFactor:

Sets the base contentScale of textures loaded on the iPhone. Useful for when you manipulate CCDirector.contenScaleFactor. Defaults to 1.0. Only valid on iOS. Not valid for OS X.

- (void)setiPhoneContentScaleFactor:(CGFloat)scale

Parameters

scale

scale factor

Discussion

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

– setiPadContentScaleFactor:

Sets the base contentScale of textures loaded on the iPad. Useful for when you manipulate CCDirector.contenScaleFactor. Defaults to 1.0. Only valid on iOS. Not valid for OS X.

- (void)setiPadContentScaleFactor:(CGFloat)scale

Parameters

scale

scale factor

Discussion

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

– setMacContentScaleFactor:

Sets the base contentScale of textures loaded on the Mac. Useful for when you manipulate CCDirector.contenScaleFactor. Defaults to 1.0. Only valid on Mac. Not valid for iOS.

- (void)setMacContentScaleFactor:(CGFloat)scale

Parameters

scale

scale factor

Discussion

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

+ sharedFileUtils

returns the shared file utils instance

+ (CCFileUtils *)sharedFileUtils

Discussion

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

– purgeCachedEntries

Purge cached entries. Will be called automatically by the Director when a memory warning is received

- (void)purgeCachedEntries

Discussion

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

– buildSearchResolutionsOrder

Calling this method will populate the searchResolutionsOrder property depending on the current device.

- (void)buildSearchResolutionsOrder

Discussion

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

– fullPathFromRelativePath:

Returns the fullpath of an filename.

- (NSString *)fullPathFromRelativePath:(NSString *)relPath

Parameters

relPath

relative path

Return Value

Full path

Discussion

If in iPhoneRetinaDisplay mode, and a RetinaDisplay file is found, it will return that path. If in iPad mode, and an iPad file is found, it will return that path.

If the filename can’t be found, it will return “relPath” instead of nil. Examples: - In iPad mode: “image.png” -> “/full/path/image-ipad.png” (in case the -ipad file exists) - In iPhone RetinaDisplay mode: “image.png” -> “/full/path/image-hd.png” (in case the -hd file exists) - In iPad RetinaDisplay mode: “image.png” -> “/full/path/image-ipadhd.png” (in case the -ipadhd file exists)

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

– fullPathFromRelativePath:contentScale:

Returns the fullpath of an filename. It will try to get the correct file for the current screen resolution. Useful for loading images and other assets that are related for the screen resolution. If in iPad mode, and an iPad file is found, it will return that path. If in iPhoneRetinaDisplay mode, and a RetinaDisplay file is found, it will return that path. But if it is not found, it will try load an iPhone Non-RetinaDisplay file.

- (NSString *)fullPathFromRelativePath:(NSString *)relPath contentScale:(CGFloat *)contentScale

Parameters

relPath

Relative path to expand.

contentScale

The resolution to search for.

Return Value

Full path

Discussion

If the filename can’t be found, it will return “relPath” instead of nil. Examples: - In iPad mode: “image.png” -> “/full/path/image-ipad.png” (in case the -ipad file exists) - In iPhone RetinaDisplay mode: “image.png” -> “/full/path/image-hd.png” (in case the -hd file exists) - In iPad RetinaDisplay mode: “image.png” -> “/full/path/image-ipadhd.png” (in case the -ipadhd file exists)

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

– fullPathFromRelativePathIgnoringResolutions:

Returns the fullpath of an filename without taking into account the screen resolution suffixes or directories. It will use the “searchPath” though. If the file can’t be found, it will return nil.

- (NSString *)fullPathFromRelativePathIgnoringResolutions:(NSString *)relPath

Parameters

relPath

Relative path.

Return Value

Full path.

Discussion

Useful for loading music files, shaders, “data” and other files that are not related to the screen resolution of the device.

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

– fullPathsOfFileNameInAllSearchPaths:

Returns all fullpaths of a filename in all search paths without taking into account the screen resolution suffixes or directories. It will use the “searchPath” though. If the file can’t be found, it will return an empty array.

- (NSArray *)fullPathsOfFileNameInAllSearchPaths:(NSString *)filename

Parameters

filename

Relative path.

Return Value

Array of full paths.

Discussion

Useful for loading the fileLookup.plist and spriteFrameFileList.plist for packages

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

– fullPathForFilename:

Returns the fullpath for a given filename. First it will try to get a new filename from the “filenameLookup” dictionary. If a new filename can’t be found on the dictionary, it will use the original filename. Then it will try obtain the full path of the filename using the CCFileUtils search rules: resolutions, and search paths

- (NSString *)fullPathForFilename:(NSString *)filename

Parameters

filename

Filename to get full path for.

Return Value

FUll path.

Discussion

If in iPad mode, and an iPad file is found, it will return that path. If in iPhoneRetinaDisplay mode, and a RetinaDisplay file is found, it will return that path. But if it is not found, it will try load an iPhone Non-RetinaDisplay file.

If the filename can’t be found on the file system, it will return nil.

This method was added to simplify multiplatform support. Whether you are using cocos2d-js or any cross-compilation toolchain like StellaSDK or Apportable, you might need to load differerent resources for a given file in the different platforms. Examples: - In iPad mode: “image.png” -> “image.pvr” -> “/full/path/image-ipad.pvr” (in case the -ipad file exists)

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

– fullPathForFilename:contentScale:

Returns the fullpath for a given filename. First it will try to get a new filename from the “filenameLookup” dictionary. If a new filename can’t be found on the dictionary, it will use the original filename. Then it will try obtain the full path of the filename using the CCFileUtils search rules: resolutions, and search paths

- (NSString *)fullPathForFilename:(NSString *)filename contentScale:(CGFloat *)contentScale

Parameters

filename

Filename to get full path for.

contentScale

scale factor

Return Value

Full path.

Discussion

If in iPad mode, and an iPad file is found, it will return that path. If in iPhoneRetinaDisplay mode, and a RetinaDisplay file is found, it will return that path. But if it is not found, it will try load an iPhone Non-RetinaDisplay file.

If the filename can’t be found on the file system, it will return nil.

This method was added to simplify multiplatform support. Whether you are using cocos2d-js or any cross-compilation toolchain like StellaSDK or Apportable, you might need to load differerent resources for a given file in the different platforms. Examples: - In iPad mode: “image.png” -> “image.pvr” -> “/full/path/image-ipad.pvr” (in case the -ipad file exists)

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

– fullPathForFilenameIgnoringResolutions:

Returns the fullpath for a given filename, without taking into account device resolution. It will try to get a new filename from the “filenameLookup” dictionary. If a new filename can’t be found on the dictionary, it will use the original filename.

- (NSString *)fullPathForFilenameIgnoringResolutions:(NSString *)key

Parameters

key

Key to get full path for.

Return Value

Full path.

Discussion

Once it gets the filename, it will try to get the fullpath for the filename, using the “searchPath”, but it won’t use any resolution search rules. If the file can’t be found, it will return nil.

Useful for loading music files, shaders, “data” and other files that are not related to the screen resolution of the device.

This method was added to simplify multiplatform support. Whether you are using cocos2d-js or any cross-compilation toolchain like StellaSDK or Apportable, you might need to load differerent resources for a given file in the different platforms. Examples: - On iOS: “sound.wav” -> “sound.caf” -> “/full/path/sound.caf” (in case the key dictionary says that “sound.wav” should be converted to “sound.caf”)

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

– loadFilenameLookupDictionaryFromFile:

Loads the filenameLookup dictionary from the contents of a filename.

- (void)loadFilenameLookupDictionaryFromFile:(NSString *)filename

Parameters

filename

Filename to query.

Discussion

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

– loadFileNameLookupsInAllSearchPathsWithName:

Loads the filenameLookup dictionary from the contents of a filename in all search paths.

- (void)loadFileNameLookupsInAllSearchPathsWithName:(NSString *)filename

Parameters

filename

Filename to query.

Discussion

Used for packages to merge filenameLookups found in different search paths.

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

– removeSuffixFromFile:

Removes the suffix from a path. On iPhone RetinaDisplay it will remove the -hd suffix On iPad it will remove the -ipad suffix On iPad RetinaDisplay it will remove the -ipadhd suffix

- (NSString *)removeSuffixFromFile:(NSString *)path

Parameters

path

Path to clean for suffix.

Return Value

Cleaned path.

Discussion

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

– standarizePath:

Stadardize a path. It calls [string stringByStandardizingPath], and if “suffix mode” is on, it will also call [self removeSuffixFromFile:path];

- (NSString *)standarizePath:(NSString *)path

Parameters

path

Path to standardize.

Return Value

Standardized path.

Discussion

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

– iPhoneRetinaDisplayFileExistsAtPath:

Returns whether or not a given path exists with the iPhone RetinaDisplay suffix. Only available on iOS. Not supported on OS X.

- (BOOL)iPhoneRetinaDisplayFileExistsAtPath:(NSString *)filename

Parameters

filename

Filename to test.

Return Value

YES if the file exists.

Discussion

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

– iPadFileExistsAtPath:

Returns whether or not a given filename exists with the iPad suffix. Only available on iOS. Not supported on OS X.

- (BOOL)iPadFileExistsAtPath:(NSString *)filename

Parameters

filename

Filename to test.

Return Value

YES if the file exists.

Discussion

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h

– iPadRetinaDisplayFileExistsAtPath:

Returns whether or not a given filename exists with the iPad RetinaDisplay suffix. Only available on iOS. Not supported on OS X.

- (BOOL)iPadRetinaDisplayFileExistsAtPath:(NSString *)filename

Parameters

filename

Filename to test.

Return Value

YES if the file exists.

Discussion

Warning: Avoid using this method in new code. See class Overview.

Declared In

CCFileUtils.h