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.

BYTE

A single unsigned integer saved in a byte

BOOLEAN

Saved as a 0 or 1 in a single byte

UINT

A unsigned integer, stored using Elias gamma encoding ( http://en.wikipedia.org/wiki/Elias_gamma_coding ). 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.

SINT

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.

FLOAT

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

STRING

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

STRING_CACHE

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

TypeNameDescription
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

CSTRING

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

Header

HEADER

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

TypeNameDescription
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

SEQUENCE

Information about one of the sequences in this document.

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

SEQUENCES

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

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

Node graph

PROPERTY

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

TypeNameDescription
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

KEYFRAME

Represents a keyframe used in animations, part of NODE_SEQUENCE_PROPERTY.

TypeNameDescription
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

NODE_SEQUENCE_PROPERY

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

TypeNameDescription
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

NODE_SEQUENCE

An animation sequence associated with a node.

TypeNameDescription
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

NODE

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.

TypeNameDescription
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

DOCUMENT

The top structure of a CCBi document.

TypeNameDescription
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)