Publishing

This article is outdated to some degree.

Publishing - General Outline

This is a general overview about the internals of the publishing process and some of the source code involved.

• Publishing is afftected by the project settings
  • Resolutions for all image assets
  • Audio quality (only wave files are converted)
  • Output directory
  • Whether or not to publish CCB files only
• Publishing a project is mainly traversing the project tree's resources which is done in the CCBPublisherclass, The resource type chapter will highlight how the different files and directories are process
• The last step is to generate some misc files
  • Create fileLookup.plist, to find files for example which are a png file in the project but are exported as jpg. This file is generated everytime.
  • A spriteFrameFileList.plist containing a dictionary of smart sprite sheet plist files
  • configCocos2d.plist keeping track of screen orientation, mode and scale. Will be read and used to set values upon startup of the project

Resource types

Sound files

• Wave files, will be converted to caf or mp4 for iOS and ogg for Android targets
• Other sound formats are not supported at the moment

Images

• PNG files are resized according to the scaling settings and if differing converted to the desired output format (jpg, pvr, pvrtc)
• Images are stored in resources-<RESOLUTION> folders which determine the scaling, see next topic for details

Smart Sprite Sheets

• Are special folders containing sprites and resources-<RESOLUTION> folders(file system), see Scaling and resources- folders topic below
• Cannot contain nested folders, publishing won't work
• All files within this folder will be converted to one sprite sheet (image and plist) per resolution
• The images of the SSS are scaled and copied first to a temp folder, normally in ~/Library/com.cocosbuilder.CocosBuilder/spritesheet/<RESOLUTION>

Bitmap fonts

• Directories with a .bmfont suffix
• Will be copied, png files inside will be optimized by optipng for release publishing

Folders

• Will be copied as is if not a smart sprite sheet or bitmap font
• Empty folders are not copied

CCB files

• Scenes, nodes, layers, sprites, particles are exported to a binary format with the .ccbi suffix

Regular files

• Files that don't fall into the above categories and have the following extenstions:

  jpg,  png, psd, pvr, ccz, mp3, m4a, caf, fnt, ttf, js, json, ccblang, plist
  

• This does not necessarily mean that these types can be added to a SB project, most are generated during publishing

• These are just copied

Scaling and resources-<RESOLUTION> folders

Please refer to the Documentation chapter 3. Managing Resources and Sounds for how scaling and overriding of auto scaling works.

Scaling from is used as an starting point to determine how the final resolution for an image is determined. For example a Scale from 2x to 2x for tablethd won't change the resolution whereas a 2x to 4x will double it.

There are five different types of resources- folders for input and output of the publishing process.

auto Is automatically created for new images and will use the different scaling settings set for every images Used only as input source for publishing

phone, phonehd, tablethd, tablet If present as input source, it will just be copied for that particular resolution. Override images are put in these. Will be created as output folder for publishing depending on the project settings

---

Coding notes

• The CCBPublisher.h/.m class needs the projectSettings and a warnings instance to work properly
• CCBPublisher will create NSOperation subclasses during traversal and add them on a suspended NSOperationQueue which is started as soon as traversal is done
• The queue is used to cancel a long running publishing process
• Be careful when adding new rules to the CCBPublisher class, operations are run later on the queue, so if there are dependencies queue those as well with a block or separate instance of NSOperation
• All operations can be found in the PublishingOperations group
• Basic logging can be toggled in the PublishLogger.h
• These operations are configured with properties and share the super class PublishBaseOperation
• PublishBaseOperation provides access to the projectSettings, warnings and a publishingTaskStatusProgress
• Use PublishBaseOperation if you need access to those aforementioned instances
  • You have to override cancel and call super to actually cancel an operation
  • Calling super in main will only provide a logging message when an operation is started, this does not conflict with Apple's guideline to not call super on an NSOperation's decendant
• PublishBaseOperation provides an initializer which should be used to create instances, all the descendants use that one and are configured afterwards with properties
• You don't need to use PublishBaseOperation, NSOperations descendants are fine
• If a new operation is a heavy duty operation provide some code in the overriden cancel method to stop the operation asap
• Use the warnings (CCBWarnings) instance to pass information to the user after the publishing is done or cancelled
• To track progress and provide text information on what's being done in a particular operation use the publishingTaskStatusProgress instance, it provides methods to "tick"" if an operation has finished and to upadte a status text
• PublishingTaskStatusProgress will pass the progress and status text back to an instance that will conform to the TaskStatusUpdaterProtocol (which in fact is the TaskStatusWindow, but don't take it for granted).
• Setting the taskStatusUpdater on an instance of CCBPublisher is optional, you won't get progress and status text updates if not done.
• Since the filelookup.plist is generated everytime from scratch make sure that a publishing operation, even skipped(e.g. a resource is up to date and doesn't need publishing), is adding the correct renaming rules. Otherwise the filelookup is overwritten. At the moment it is not possible to cache the filelookup.plist to prevent this. The generation of sprite sheets are a special case, where intermediate lookup files are generated to create a valid filelookup.plist for skipped smart spritesheet publishing operations. These files are stored in the smart spritesheet folder. The renaming rules are created in preceding image operations which are not invoked if the spritesheet is up to date. The intermediate lookups are used every time the user publishes so the final lookup is always valid.