X1. Creating Node Plug ins

CocosBuilder - Create Node Plug-in

Node plug-ins can be used to add custom type of objects that can be used in and exported from CocosBuilder. The objects needs to be a direct or indirect sub-class of CCNode.

Setting up the project

The easiest way to setup your Xcode project for a new plug-in is to duplicate the example project in the PlugIn Nodes folder.

Now, open the project and slowly click twice on the project name in the file view to rename it. Name it after the class you want to create a plug-in for.

You will be asked to rename some project content items. Leave everything checked and click Rename. You now have a new project for your plug-in.

To compile and test the plug-in, first make sure that you have built a copy of CocosBuilder and that it is located in the build directory. The click the Run button in the plug-in project. This will compile the plug-in and copy it into CocosBuilder's PlugIns folder (inside the app bundle). For testing and debugging, double click the CocosBuilder program in the build directory. You can see the output of the program using Console.app, set the filter to CocosBuilder to avoid output from other applications.

Basic plug-in structure

To make a working node plug-in, you will need to add your class to the plug-in project and edit the CCBPProperties.plist file. When loading your custom class CocosBuilder/CCBReader will create it using alloc and default init method, then assign all the object's properties. Therefore, it is required that your class can be initialized using the init method only (without using a custom init-method).

The classes you add to a plug-in is linked in runtime against the Cocos2d library, only the header files are included in the project. If your node-object uses more than one class, those classes shouldn't be included in other plug-ins or there may be conflicts when loading the plug-ins.

For many types of nodes you can just drop their classes into the plug-in, setup their editable properties in the CCBPProperties.plist file and you are good to go. Sometimes it may be necessary to use a different class for displaying a node in the editor then when loading it into an app. Most often, it is easiest to use a sub-class of your node and override some of it's behavior. E.g. you can disable animations or user actions in the sub-class. If you use this approach you should name your sub-class with the CCBP prefix (e.g. CCBPMyCocosNode if your class is CCMyCocosNode).

Adding a plug-in built into CocosBuilder

Note that only plug-ins that are very general should be included in CocosBuilder by default. These are, for instance, core cocos2d classes and the GUI components bundled with CocosBuilder.

In order to create a built in plug-in, you need to perform the following steps:

1. Create a new Bundle target for the plug-in, name it after the plug-ins main class.
2. In the plug-in target's build settings, set "Wrapper Extension" to "ccbPlugNode" and set "Other Linker Flags" to "-undefined dynamic_lookup".
3. Select the CocosBuilder target and go to Build Phases. Add your new plug-in target to the Target Dependencies by dragging and dropping from the Targets on the left side.
4. Also in the Build Phases, add your plug-in it to the Copy PlugIns phase.
5. When adding classes and resource to the plug-in, be carful to only add them to the plug-in target.

CCBPProperties.plist format

Most of the plug-in magic happens in the CCBPProperties.plist file. It defines all properties of your class that can be edited in CocosBuilder and other information about the plug-in. The file is structured as follows.

Required keys

Key	Type	Comment
className	String	The name of the main class when loaded into an app, e.g. CCMyCocosNode
editorClassName	String	The name of the class used by the editor (often the same as className), e.g. CCBPMyCocosNode
inheritsFrom	String	The name of the class's super class, this is used to display the inspector panels of the super class, e.g. CCSprite
canHaveChildren	Boolean	Yes, if it should be possible to add children to this node in CocosBuilder
properties	Array	List of PlugInProperty as described below

Optional keys

Key	Type	Comment
propertiesOverridden	Array	The format is the same as for the properties-key, but it replaces a property of a super class
spriteFrameDrop	Dictionary	Specifies what class of object will be created when a sprite frame is dropped on the node. E.g. CCMenuItemImage for a CCMenu, see SpriteFrameDrop described below for details
requireChildClass	Array	Array of String:s that defines which classes are allowed as children for this node. E.g. CCMenu only allows CCMenuItemImage as children
requireParentClass	String	Specifies if this node can only be added as child to a specific type of node. E.g. CCMenuItemImage can only be added to CCMenu.

PlugInProperty

A PlugInProperty defines how a property should be displayed in CocosBuilder and how it should be loaded into an app by CCBReader. It is a dictionary with the following keys. Which property type:s are supported and how they are serialized (for the default value) is defined in the Property Types document.

Required keys

Key	Type	Comment
type	String	The property type, e.g. Point or Float
displayName	String	What label should be associated with the type, e.g. Content Size
name	String	The name of the property to set on the node (not required for type Separator, SeparatorSub and StartStop)

Optional keys

Key	Type	Comment
default	n/a	Default value, serialized as described in the Property Types document
readOnly	Boolean	Set to YES if this property should be read only, e.g. YES for contentSize in CCSprite
dontSetInEditor	Boolean	If set to YES this property will not be set or read from the node by the editor. Instead, the value will be saved in a separate variable. Requires the default value to be specified
platform	String	Set this key if the property should only be used on a specific platform. Valid values are Mac or iOS.
affectsProperties	Array	Array of String:s that defines which other properties should be updated when this value changes. E.g. when changing the texture of a sprite, it affects its contentSize
extra	String	Different uses for different type:s, see the Property Types document for details.

SpriteFrameDrop

The SpriteFrameDrop structure is used to specify the behavior when a sprite frame is dropped onto a scene from the assets palette.

Required keys

Key	Type	Comment
className	String	The name of the class to create, e.g. CCSprite
property	String	The name of the property to assign the dropped sprite frame to, e.g. displayFrame for CCSprite