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.
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 ( 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.
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);
To save space, all strings are written to a string cache at the beginning of the file.
| Type | Name | Description |
|---|---|---|
| UINT | numStrings | Number of strings in the string cache |
| STRING | str[0] | First string in cache |
| STRING | str[1] | Second string in cache |
| … | ||
| STRING | str[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.
| Type | Name | Description |
|---|---|---|
| BYTE | magic0 | Must be 'i' |
| BYTE | magic1 | Must be 'b' |
| BYTE | magic2 | Must be 'c' |
| BYTE | magic3 | Must be 'c' |
| UINT | version | Must be 4 |
| BOOLEAN | jsControlled | True if the file is using a JS Controller object |
Information about one of the sequences in this document.
| Type | Name | Description |
|---|---|---|
| FLOAT | duration | Length of the sequence in seconds |
| CSTRING | name | Name of the sequence |
| UINT | sequenceId | Id of the sequence |
| SINT | chainedSequenceId | Id 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.
| Type | Name | Description |
|---|---|---|
| UINT | numSequences | Number of sequences used in this document |
| SEQUENCE | seq[0] | First sequence |
| SEQUENCE | seq[1] | Second sequence |
| … | ||
| SEQUENCE | seq[numSequences-1] | Last sequence |
Represents a property of a node. For type IDs and how they are serialized, see the Property Types document.
| Type | Name | Description |
|---|---|---|
| UINT | typeID | ID of the type |
| CSTRING | propertyName | The name of the property |
| BYTE | platform | The type of platform the property is supported for. Can be 0 = any platform, 1 = iOS only, 2 = Mac only |
| n/a | serializedValue | Value serialized as described in the Property Types document |
Represents a keyframe used in animations, part of NODE_SEQUENCE_PROPERTY.
| Type | Name | Description |
|---|---|---|
| FLOAT | time | The time in seconds of the keyframe |
| UINT | easingType | The type of easing used in between this keyframe and the following. (Easing types defined in table below) |
| FLOAT | easingOpt | Setting 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/a | serializedValue | Value serialized as describe in the Property Types document under Animated Properties |
Easing types used by KEYFRAME:
| Value | Easing 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.
| Type | Name | Description |
|---|---|---|
| CSTRING | name | Name of the sequence |
| UINT | type | The type of the property (defined in Animated Properties) |
| UINT | numKeyframes | Number of keyframes used by this property |
| KEYFRAME | keyframe[0] | First keyframe |
| KEYFRAME | keyframe[1] | Second keyframe |
| … | ||
| KEYFRAME | keyframe[numKeyframes-1] | Last keyframe |
An animation sequence associated with a node.
| Type | Name | Description |
|---|---|---|
| UINT | numProperties | Number of animated properties in this sequence |
| NODE_SEQUENCE_PROPERTY | property[0] | The first property used in the sequence |
| NODE_SEQUENCE_PROPERTY | property[1] | The second property used in the sequence |
| … | ||
| NODE_SEQUENCE_PROPERTY | property[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.
| Type | Name | Description |
|---|---|---|
| CSTRING | class | Name of the nodes class |
| CSTRING | jsController | Name of the js controller, only written if jsControlled is set in the HEADER |
| UINT | memberVarAssignmentType | The target this node should be assigned as a variable for. 0 = No target, 1 = documents root node, 2 = owner (as passed to CCBReader) |
| CSTRING | memberVarAssignmentName | The name of the variable this node should be assigned to (only written if memberVarAssignmentType != 0) |
| UINT | numSequences | Number animation sequences saved for this node |
| NODE_SEQUENCE | sequence[0] | The first sequence of this node |
| NODE_SEQUENCE | sequence[1] | The second sequence of this node |
| … | ||
| NODE_SEQUENCE | sequence[numSequences-1] | The last sequence of this node |
| UINT | numRegularProperties | Number of regular properties saved for this node |
| UINT | numExtraProperties | Number of regular properties saved for this node |
| PROPERTY | property[0] | The first property of this node |
| PROPERTY | property[1] | The second property of this node |
| … | ||
| PROPERTY | property[numRegularProperties+numExtraProperties-1] | The last property of this node |
| UINT | numChildren | Number of children of this node |
| NODE | child[0] | The first child of this node |
| NODE | child[1] | The second child of this node |
| … | ||
| NODE | child[numProperties-1] | The last child of this node |
The top structure of a CCBi document.
| Type | Name | Description |
|---|---|---|
| HEADER | header | Document header |
| STRING_CACHE | stringCache | All strings referenced by this file |
| SEQUENCES | sequences | Information about the animation sequences used in this file |
| NODE | rootNode | The root node of this document (which can also have children) |