Packages

Packages

Packages are work in progress. Please report Sprite Builder bugs and feature requests to [Sprite Builder's github page](https://github.com/Sprite Builder/Sprite Builder/). Cocos2d bugs and feature requests to Cocos2d's github home. If you need help using packages the [Sprite Builder forum](http://forum.Sprite Builder.com/) or Cocos2d forum are good places to start. We are looking forward to getting your feedback.

There will be an example app and updated Sprite Builder project templates soon.

A package is a zipped folder created with Sprite Builder. The general idea is to add content to an app during runtime which is located on a remote host. A package can be used to add any kind of file to an app. A feature is to patch existing assets.

General Flow of the Package Manager

• Download a package from a remote host using http
• Unzipping after download
• Install: Copy contents of unzipped archive to the installation folder, usually /Library/Caches/Packages/<package-identifier> (See naming convention)
• Enable in Cocos2d: Include new packages in search path, reload all sprite sheets and filename lookups

Getting Started

First of all you will need a package to be downloadable on a host. Note down the URL. Let's assume a package archive name: DLC-iOS-phonehd.zip (See below for naming conventions). The full URL is http://foobar.com/packages/DLC-iOS-phonehd.zip. OS is iOS.

To make the package available in your app the only the following lines are needed:

// 1.
[CCPackageManager sharedManager].baseURL = [NSURL URLWithString:@"http://foobar.com/packages"];
// 2.
[[CCPackageManager sharedManager] downloadPackageWithName:@"DLC"
                                               resolution:@"phonehd"
// 3.
                                      enableAfterDownload:YES]

1. Is setting the baseURL to the host, note that the package file name is removed. This is a one time setup, especially helpful if you have several packages ready for download. This method also returns a freshly created CCPackage instance if needed.
2. This schedules a downlod as mentioned in the general flow of the Package Manager
3. If enableAfterDownload: is set to NO the package is installed but not enabled in cocos2d

Note: The final URL is created as the OS is known.

Load packages on startup

If a package is already installed and enabled you will need to load and persist the package data.

A good place to load packages is after cocos2d has been configured, for example in application:didFinishLaunchingWithOptions:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
...
	// 1.
    [self setupCocos2dWithOptions:cocos2dSetup];

	// 2.
    [[CCPackageManager sharedManager] loadPackages];
...
}

1. Always set up cocos2d first, this is just the example call of the template project.
2. The package manager loads the packages from disk(NSUserDefaults), reinstate paused downloads, restarts unfinished unzipping tasks and finally enables packages if they were enabled last time the app ran

Note: Calling the loadPacakges method more than once won't do anything.

Save packages

As of this writing the dev has to take care of calling the method to persist packages. This may change. A recommended way is to persist whenever the app closes or is being terminated. Using the following example should ensure a persisted packages state.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{

...
	// 1. 	
    [[NSNotificationCenter defaultCenter] addObserver:self
                                             selector:@selector(savePackages)
                                                 name:UIApplicationDidEnterBackgroundNotification 
                                               object:nil];
    [[NSNotificationCenter defaultCenter] addObserver:self
                                             selector:@selector(savePackages)
                                                 name:UIApplicationWillTerminateNotification 
                                               object:nil];
...                                               
}

// 2.
- (void)savePackages
{
    [[CCPackageManager sharedManager] savePackages];
}

1. Default notification center used to trigger the savePackage method when the app closes or terminates
2. Wrapper for the savePackages method for notification events

Naming Convention

The <package identifier> should follow the naming convention <name>-<os>-<resolution>

• name: freely chosen name, try to avoid white spaces
• os: iOS, Android, Mac
• resolution: usually phone, phonehd, tablet, tablethd

A zipped package is named <name>-<os>-<resolution>.zip

Anatomy of a Package

A zipped package should contain only one folder with the naming convention of the package identifier. That folder is the package folder. That folder can contain anything you'd like to integrate in your app. Usually the content will similarly structured like the Published folder created by Sprite Builder. That means there should be a spriteFrameFileList.plist file located at the top level within the package folder if you want to include sprite sheets in your package.

A fileLookup.plist should be present if files have been converted by Sprite Builder to a different format, like a wave file converted to ogg for Android. This file is usually generated by Sprite Builder during publishing.

The configCocos2d.plist is not used at the moment.

An example for a package called DLC targeted for iOS, resolution is phonehd:

DLC-iOS-phonehd.zip
	/DLC-iOS-phonehd
		/sounds
			mow.mp4
		/resources-phonehd
			spritesheet_spaceships.png
			spritesheet_spaceships.plist
			non_spritesheet_sprite.png
		spriteFrameFileList.plist
		fileLookup.plist
		configCocos2d.plist		

Packages created with Sprite Builder meet all these requirements.

Patching content

Patching content is simply using the same asset name as in the main bundle. The ordering of Cocos2d search paths is important. Usually the package manager will make packages take precedence over the main published resources folder. See also notes below regarding taking effect of patched scenes/sprites.

Notes

• It is not recommended to install more than one resolution of a package on a device. This can lead to unwanted search path ordering and wrong assets being loaded.

• After installing and enabling a package patched assets won't take effect in present scenes residing in memory. You will have to reload those scenes/assets.

• From Apple's documentation regarding the /Library/Caches folde default location for installed packages:

  • Use this directory to write any app-specific support files that your app can re-create easily. Your app is generally responsible for managing the contents of this directory and for adding and deleting files as needed.

  • In iOS 2.2 and later, the contents of this directory are not backed up by iTunes. In addition, iTunes removes files in this directory during a full restoration of the device.

  • On iOS 5.0 and later, the system may delete the Caches directory on rare occasions when the system is very low on disk space. This will never occur while an app is running. However, you should be aware that iTunes restore is not necessarily the only condition under which the Caches directory can be erased.

• /Library/Application Support might also be a good place to install packages to, the contents of this directory are backed up by iTunes.