Find file
Fetching contributors…
Cannot retrieve contributors at this time
428 lines (353 sloc) 11.7 KB

CocosBuilder - CCBi File Format

This is a description of the CocosBuilder export (publish) file format for Cocos2d-iphone. It is a binary file format designed to be as compact as possible and very quick to load. This document covers version 4 of the ccbi file format, relased with CocosBuilder 3. If you are implementing or porting a reader for the ccbi file format, you may want to also have a look at the CCBReader, which is the reference implementation.

Basic types

The file format is built upon a set of basic types, such as integers, floats and strings.


A single unsigned integer saved in a byte


Saved as a 0 or 1 in a single byte


A unsigned integer, stored using Elias gamma encoding ( ). Before being stored, 1 is added to the number to support 0 values. The last byte is padded with 0:s so that the next written value is aligned to even bytes.


A signed integer, stored using Elias gamma encoding. Before being stored, the number is transformed to a positive integer using bijection. 0 -> 1, -1 -> 2, 1 -> 3, -2 -> 4, 2 -> 5, etc.


The first byte of the float defines how it is stored. Possible values are:

  • 0 -> 0.0f
  • 1 -> 1.0f
  • 2 -> -1.0f
  • 3 -> 0.5f
  • 4 -> Saved as INT
  • 5 -> Saved as full 4 byte float number


Strings are saved as Java-style UTF8:s. The first two bytes define the length of the string, then the string is saved using UTF8 encoding (without a trailing \0);

Strings and String cache


To save space, all strings are written to a string cache at the beginning of the file.

UINTnumStringsNumber of strings in the string cache
STRINGstr[0]First string in cache
STRINGstr[1]Second string in cache
STRINGstr[numStrings-1]Last string in cache


A cached string is saved using a single UINT which refers to the strings index in the string cache.



The header is used to ensure the file has the right type and version.

BYTEmagic0Must be 'i'
BYTEmagic1Must be 'b'
BYTEmagic2Must be 'c'
BYTEmagic3Must be 'c'
UINTversionMust be 4
BOOLEANjsControlledTrue if the file is using a JS Controller object

Animation Sequences


Information about one of the sequences in this document.

FLOATdurationLength of the sequence in seconds
CSTRINGnameName of the sequence
UINTsequenceIdId of the sequence
SINTchainedSequenceIdId of a chained sequence or -1 if none


Provides information about the animation sequneces (timelines) used by this document. The actual keyframes are saved together with the nodes.

UINTnumSequencesNumber of sequences used in this document
SEQUENCEseq[0]First sequence
SEQUENCEseq[1]Second sequence
SEQUENCEseq[numSequences-1]Last sequence

Node graph


Represents a property of a node. For type IDs and how they are serialized, see the Property Types document.

UINTtypeIDID of the type
CSTRINGpropertyNameThe name of the property
BYTEplatformThe type of platform the property is supported for. Can be 0 = any platform, 1 = iOS only, 2 = Mac only
n/aserializedValueValue serialized as described in the Property Types document


Represents a keyframe used in animations, part of NODE_SEQUENCE_PROPERTY.

FLOATtimeThe time in seconds of the keyframe
UINTeasingTypeThe type of easing used in between this keyframe and the following. (Easing types defined in table below)
FLOATeasingOptSetting used with the easing (rate for cubic and period for elastic). This is only saved if easing type is 2,3,4,5,6, or 7
n/aserializedValueValue serialized as describe in the Property Types document under Animated Properties

Easing types used by KEYFRAME:

ValueEasing type
0 Instant
1 Linear
2 Cubic in
3 Cubic out
4 Cubic in/out
5 Elastic in
6 Elastic out
7 Elastic in/out
8 Bounce in
9 Bounce out
10 Bounce in/out
11 Back in
12 Back out
13 Back in/out


A property used in an animation sequence for a specific node, contains a set of keyframes. All keyframes are saved ordered by there time.

CSTRINGnameName of the sequence
UINTtypeThe type of the property (defined in Animated Properties)
UINTnumKeyframesNumber of keyframes used by this property
KEYFRAMEkeyframe[0]First keyframe
KEYFRAMEkeyframe[1]Second keyframe
KEYFRAMEkeyframe[numKeyframes-1]Last keyframe


An animation sequence associated with a node.

UINTnumPropertiesNumber of animated properties in this sequence
NODE_SEQUENCE_PROPERTYproperty[0]The first property used in the sequence
NODE_SEQUENCE_PROPERTYproperty[1]The second property used in the sequence
NODE_SEQUENCE_PROPERTYproperty[numProperties-1]The last property used in the sequence


Represents a node or a node graph (if the node has children). Nodes that uses the CCBFile class (sub ccb-files) are handled slightly different when loaded. The node graph associated with the ccbFile property should replace the CCBFile node, but some the properties by the CCBFile node should override the ones in the ccbFile property. The properties that should be overriden are; all extra properties, and position, rotation, scale, tag and visible.

CSTRINGclassName of the nodes class
CSTRINGjsControllerName of the js controller, only written if jsControlled is set in the HEADER
UINTmemberVarAssignmentTypeThe target this node should be assigned as a variable for. 0 = No target, 1 = documents root node, 2 = owner (as passed to CCBReader)
CSTRINGmemberVarAssignmentNameThe name of the variable this node should be assigned to (only written if memberVarAssignmentType != 0)
UINTnumSequencesNumber animation sequences saved for this node
NODE_SEQUENCEsequence[0]The first sequence of this node
NODE_SEQUENCEsequence[1]The second sequence of this node
NODE_SEQUENCEsequence[numSequences-1]The last sequence of this node
UINTnumRegularPropertiesNumber of regular properties saved for this node
UINTnumExtraPropertiesNumber of regular properties saved for this node
PROPERTYproperty[0]The first property of this node
PROPERTYproperty[1]The second property of this node
PROPERTYproperty[numRegularProperties+numExtraProperties-1]The last property of this node
UINTnumChildrenNumber of children of this node
NODEchild[0]The first child of this node
NODEchild[1]The second child of this node
NODEchild[numProperties-1]The last child of this node

Overall document structure


The top structure of a CCBi document.

HEADERheaderDocument header
STRING_CACHEstringCacheAll strings referenced by this file
SEQUENCESsequencesInformation about the animation sequences used in this file
NODErootNodeThe root node of this document (which can also have children)