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
- -(NSString) fullPathForFilename:(NSString)key contentScale:(CGFloat *)contentScale;
- -(NSString) fullPathForFilenameIgnoringResolutions:(NSString)key;
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