X2. Creating Export Plug ins

CocosBuilder - Create export plug-in

CocosBuilder has support for creating custom export plug-ins. Bundled with CocosBuilder comes the default ccbi-exporter, but it is easy to add new output formats.

Setup a new plug-in project

The easiest way to setup a new plug-in project is to duplicate and rename the example plug-in. Open the PlugIn Exporters folder and duplicate the Export Example folder. Rename it to what you want your new export plug-in to be called.

Now open the Xcode project in the new folder. Rename the project by clicking slowly twice on the projects name. The name you use here is what will be displayed in the save dialog when selecting Publish As… in CocosBuilder.

You will now be asked to rename various project content items. Keep everything selected and click the Rename button.

The plug-in uses a custom class to export your CocosBuilder document. This class's name needs to be unique for each plug-in. Therefore, you will need to rename the plug-in's main class. This is easiest done by opening the file, right clicking on the class's name and selecting Refactor -> Rename.

Enter a name that corresponds to your plug-in's name and use the CCBX prefix. You will also need to open the Info.plist file and change the Principal class property to the name of your new class.

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.

Write the plug-in

The export plug-in is very simple in it's structure. It's main class should contain two methods that CocosBuilder will call. The first method, extension, simply returns a string with the extension that the exported file should use. For instance, this is what the default ccbi exporter uses.

- (NSString*) extension
{
    return @"ccbi";
}

The second method, exportDocument: is where all the magic of the exporter happens. It will receive a NSDictionary that contains the complete document. The document structure can be found in the CCB File Format. The exportDocument: should create and return an autoreleased NSData object with the contents of the file to export. The example file uses NSPropertyListSerialization to create a plist representation of the document (same as ccb file save).

- (NSData*) exportDocument:(NSDictionary*)doc
{
    return [NSPropertyListSerialization dataFromPropertyList:doc format:NSPropertyListBinaryFormat_v1_0 errorDescription:NULL];
}