My company is developing a game for the iPhone and iPad devices using Flash cs5.5 and Air3.0
The client requires that certain features be supported - such things like GameCenter, Rating system, etc... none of which is currently supported by flash for the iOS.
However, they did provide us with a bunch of xCode sample files on how they want things to work.
My idea was to bridge the gap in functionality by creating a native exention that utilized the xcode source that was given to me, thus giving me the functionality that is required.
But first, I need to actually CREATE a native extension, even just a basic echo/hello world... I have followed all the steps from various guides and tutorials and I have managed to create an ipa and put it on my iPad2 to test, but when the program starts up, nothing happens, I am left with a black screen. When I comment out the lines of code that intialize the extension, it fires up just fine.
(and yes, I even tried to put things in try blocks in case there was an error - no luck)
So I am hoping that someone can read through the process of what I am doing below and point out what I am doing wrong, or what I am missing.
What I am using:
Mac Mini running OSX 10.7.2 - this is used to run xCode 4.1 build 4B110
PC - Windows 7 home 64bit - Running Flash CS5.5 (version 11.5.1.3469) with the AIR 3.0 SDK inside it. I also have the AIR 3.0 sdk in a seperate folder for command line running. (This is my primary developement platform)
The PC does have flash builder installed, but I have never really used it, nor do I know how to use it... everything that has been built to date has been done using Flash CS5.5
So, this is what I have done.
The first thing I do is create a .a static library on the mac.
I open xcode and create a new project.
- Select iOS Framework and Library, then select "Cocoa touch Static Library"
- Give it a name, in this case "EchoExtension" and put it in a folder.
- I then delete the EchoExtension.h file as all the samples I have seen to date don't use it.
- I then add "FlashRuntimeExtension.h" to the project from the AIR3.0 sdk frameworks folder on my PC
- I then delete everything in my .m file and, following several different examples and tutorials, type up the following code:
//
// EchoExtension.m
// EchoExtension
//
#include "FlashRuntimeExtensions.h"
FREObject echo(FREContext ctx, void* funcData, uint32_t argc, FREObject argv[]) {
return argv[0];
}
//----------- Extention intializer and finalizer --------------------------------------------------------------------- ---------------------------------------------------------------------- -----------------------------------------
// A native context instance is created
void ContextInitializer(void* extData, const uint8_t* ctxType, FREContext ctx, uint32_t* numFunctionsToTest, const FRENamedFunction** functionsToSet) {
// setup the number of functions in this extention
// for easy reference, set the number of function that this extention will use.
int FunctionCount = 1;
// set the pointer reference to the number of function this extention will use.
*numFunctionsToTest = FunctionCount;
// create an array to store all the functions we will use.
FRENamedFunction* func = (FRENamedFunction*)malloc(sizeof(FRENamedFunction)*FunctionCount);
// create an array entry for each function
func[0].name = (const uint8_t*)"echo"; // the name of the function
func[0].functionData = NULL; // the data type
func[0].function = &echo; // reference to the actual function
// save the array in a pointer.
*functionsToSet = func;
}
// A native context instance is disposed
void ContextFinalizer(FREContext ctx) {
return;
}
// Initialization function of each extension
void ExtInitializer(void** extDataToSet, FREContextInitializer* ctxInitializerToSet, FREContextFinalizer* ctxFinalizerToSet) {
*extDataToSet = NULL;
*ctxInitializerToSet = &ContextInitializer;
*ctxFinalizerToSet = &ContextFinalizer;
}
// Called when extension is unloaded
void ExtFinalizer(void* extData) {
return;
}
- I then go "Product", "Build" and it creates libEchoExtension.a
- I copy this .a file over to my PC.
I am now finish with that god foresaken mac (*shudders*)
Back on my PC, I create a folder for my test project. For all intents an purposes, let's call this "D:\src\EchoExtension" I then create 2 folders, one called "lib" and one called "app". Lib is where I will create the actionscript source for my extension.
- In my lib folder, I create a new fla in flash cs5.5 called "EchoExtension.fla"
- I create in my lib folder, the following:
- com\extensions\EchoExtension\EchoExtension.as
- a folder called "Build" in which I place my libEchoExtension.a file.
- in my EchoExtension.as file, I place the following code:
package com.extensions.EchoExtension
{
import flash.events.EventDispatcher;
import flash.events.IEventDispatcher;
import flash.external.ExtensionContext;
public class EchoExtension extends EventDispatcher
{
protected var _extensionContext:ExtensionContext;
/**
* Constructor.
*/
public function EchoExtension()
{
super();
// Initialize extension.
_extensionContext = ExtensionContext.createExtensionContext( "com.extensions.EchoExtension", "main" );
}
public function echo(Prompt:String):String
{
return _extensionContext.call( "echo" ) as String;
}
}
}
- In my main fla, on the first layer of the time line, I simply put the following code to make sure that the as file get's included when I publish the swc.
import com.extensions.EchoExtension.EchoExtension;
var ext:EchoExtension = new EchoExtension();
stop();
- I then open up my fla's publish settings, turn off the swf - which I don't need, and check the swc and make sure that it outputs into my build folder. "./Build/EchoExtension.swc"
- I also set the player to Air 3.0 (which I can do since I have successfully integrated AIR 3.0 along side my AIR 2.6 and can build both without any problems)
- I then publish the swc. So far, so good. No problems.
- I then make a copy of the swc and rename it to EchoExtension.swc.zip, at which point I extract the library.swf file from it and also place it in my build folder.
- I then create extension.xml in by build folder which contains the following code:
<extension xmlns="http://ns.adobe.com/air/extension/2.5">
<id>com.extensions.EchoExtension</id>
<versionNumber>1</versionNumber>
<platforms>
<platform name="iPhone-ARM">
<applicationDeployment>
<nativeLibrary>libEchoExtension.a</nativeLibrary>
<initializer>ExtInitializer</initializer>
<finalizer>ExtFinalizer</finalizer>
</applicationDeployment>
</platform>
</platforms>
</extension>
- Now, at this point I am a little wary, because I am building for the iPad2... the platform is iPhone... I thought that may be a problem and at one point I tested the same build on the iPhone4 and had the same results. I have also tested it using the platform name of iPad-ARM and got the same results... So I don't think that is the problem, but I am unsure.
- Now, to make things easier, I created a batch file called "buildane.bat" in my build folder. This is what I will use to create my .ane file and it contains the following command line:
D:\SDKs\AirSDK30\bin\adt -package -target ane EchoExtension.ane extension.xml -swc EchoExtension.swc -platform iPhone-ARM library.swf libEchoExtension.a
- I then open a command prompt and run buildane.bat and poof. My ane is created. My build folder has the following files in it now:
- buildane.bat
- EchoExtension.ane
- EchoExtension.swc
- EchoExtension.swc.zip
- extension.xml
- libEchoExtension.a
- library.swf
Now that I have my swc, ane, and all that, it's time to create my sample application that will be used to test my new extension.
- I go back to my D:\src\EchoExtension folder and go into the app folder I created ealier.
- I then create a new flash project called EchoExtensionTester.fla
- I open the action script settings, library paths, and add the swc that I created in my D:\src\EchoExtension\lib\build folder to my project.
- On my stage, I create an input text field called txtInput, a dynamic text field called txtEcho, and a couple of buttons called btnClear, btnRuntime, and btnEcho
- I open up the first layer in the time line and place the following code:
// basic imports.
import flash.desktop.NativeApplication;
import flash.events.MouseEvent;
import flash.text.TextField;
// import the extension from our swc.
import com.extensions.EchoExtension.EchoExtension;
// set our input text field to need the softkeyboard
txtInput.needsSoftKeyboard = true;
// add the event handlers to our buttons.
btnEcho.addEventListener(MouseEvent.CLICK, btnEcho_Click);
btnClear.addEventListener(MouseEvent.CLICK, btnClear_Click);
btnRunTime.addEventListener(MouseEvent.CLICK, btnRunTime_Click);
// create our extension variable.
var ext:EchoExtension;
try
{
// initialize our echo extension.
ext = new EchoExtension();
} catch (e:Error) {
txtEcho.text = "Error trying to create new EchoExtension:\n\n" + e;
}
stop();
// clear the echo text field
function btnClear_Click(e:MouseEvent):void
{
txtEcho.text = "";
}
// just for testing, put the current version of air runtime into our text field so we can make sure we are running air 3.0
function btnRunTime_Click(e:MouseEvent):void
{
txtEcho.text += "\nRuntime version = " + NativeApplication.nativeApplication.runtimeVersion;
}
// call the extension, passing it whatever is in the input text field and have it return it and place it in our echo text field
function btnEcho_Click(e:MouseEvent):void
{
txtEcho.text += "\n";
try
{
txtEcho.text += ext.echo(txtInput.text);
} catch (e:Error) {
txtEcho.text += "\nError calling ext.echo: " + e;
}
}
- I then save the project, Open the Air for iOS settings and set the following: (but yes, I know... I am going to have to use adt to do the build, but I need to create the swf first)
- Output file: EchoExtensionTester.ipa
- Appname: EchoExtensionTester
- Version 1.0
- Landscape
- Fullscreen On
- Auto orientation is off
- rendering GPU
- device: iPad and iPhone
- Res: High
- Deployement: I use my certificate and provisionging profile that I use for my Primary project (which work) and set for device testing.
- I close the window and save again... but before I publish, I open newly created "EchoExtensionTester-app.xml" that is in my app folder.
- I add <extensions> <extensionID>com.extensions.EchoExtension</extensionID> </extensions> to the xml file so now it looks like this:
<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<application xmlns="http://ns.adobe.com/air/application/3.0">
<extensions>
<extensionID>com.extensions.EchoExtension</extensionID>
</extensions>
<id>EchoExtensionTester</id>
<versionNumber>1.0</versionNumber>
<filename>EchoExtensionTester</filename>
<description/>
<!-- To localize the description, use the following format for the description element.<description><text xml:lang="en">English App description goes here</text><text xml:lang="fr">French App description goes here</text><text xml:lang="ja">Japanese App description goes here</text></description>-->
<name>EchoExtensionTester</name>
<!-- To localize the name, use the following format for the name element.<name><text xml:lang="en">English App name goes here</text><text xml:lang="fr">French App name goes here</text><text xml:lang="ja">Japanese App name goes here</text></name>-->
<copyright/>
<initialWindow>
<content>EchoExtensionTester.swf</content>
<systemChrome>standard</systemChrome>
<transparent>false</transparent>
<visible>true</visible>
<fullScreen>true</fullScreen>
<aspectRatio>landscape</aspectRatio>
<renderMode>gpu</renderMode>
<maximizable>true</maximizable>
<minimizable>true</minimizable>
<resizable>true</resizable>
<autoOrients>false</autoOrients>
</initialWindow>
<icon/>
<customUpdateUI>false</customUpdateUI>
<allowBrowserInvocation>false</allowBrowserInvocation>
<iPhone>
<InfoAdditions>
<![CDATA[<key>UIDeviceFamily</key><array><string>1</string><string>2< /string></array>]]>
</InfoAdditions>
<requestedDisplayResolution>high</requestedDisplayResolution>
</iPhone>
</application>
- I save the changes to the xml and go back to flash. I then publish.
- The swf is created as it should be, but then I get the error message:
Error creating files.
An implmentation for native extension 'com.extensions.EchoExtension' required by the application was not found for the target platform.
- Now, while this is a pain in the rear, I new this was going to happen because in my reading of tutorials and samples, they all said that you must use adt to build the ipa... but that's fine... all I wanted anyway was the swf, which I now have in my app folder.
- I close down flash as I don't need it anymore and I create a new batch file: (note: I change the names of the cert, provision profile, and password for this post)
cls
"D:\SDKs\AirSDK30\bin\adt" -package -target ipa-ad-hoc -storetype pkcs12 -keystore "D:\src\mycert.p12" -storepass MYPASSWORD -provisioning-profile "D:\src\myprovfile.mobileprovision" "EchoExtensionTester.ipa" "EchoExtensionTester-app.xml" "EchoExtensionTester.swf" -extdir ../lib/Build
set /p dummy=
echo done
- I then open a command window in my app folder and run build.bat...
- I wait about 2 minutes....
- ...
- ...
- YAY! My ipa file has been created with no errors reported so far.... Time to copy this bad boy to the iPad and see what happens.
- I open iTunes, drag "EchoExtensionTester.ipa" over to the Apps, then sync my device....
- ...
- YAY! iTunes has successfully installed the ipa on the device... and there is by bright and shiney blank icon for Echo Extension Tester...
- I open the app.... and.....
- nothing.
- I wait
- still nothing.
- I go to the bathroom.
- I get back... still nothing... just a black screen.
- I press the iPad home button, the app minimized, I restore it... nothing... black screen.
hrm. Time to do a little trial and error to see if I can figure out where the break down is.
- As a test, I open my fla and I comment out the following lines:
- ext = new EchoExtension();
- txtEcho.text += ext.echo(txtInput.text);
- I then rebuild the swf... get the same error (don't care)... I then rebuild the ipa using the batch file.... and re-install it on the device when it's done.
- The exact same thing....
- I open the xml file... and remove the <extensionID>com.extensions.EchoExtension</extensionID> line, save and re-run the batch file again... wait for the ipa to finish, and run it on the device.
- I fire up the program on the iPad and it launches perfectly... except for the commented line of code to actually create and call the extension, everything works as it should. The runtime on the device is reporting as 3.0.0.4080
- As a test, I open the .fla back up and uncomment the 2 lines I commented out above... keeping the extensionID out of the xml file, I re-publish the ipa.... of course, this time, it actually creates the ipa from flash because the extension id is not in the xml.
- I put the ipa file with the extension code in place on the ipad... Fire it up and put some text into the txtInput and press the echo button. I get the following error:
- Error calling ext.echo: TypeError: Error #1009
- I suspect that is because I failed into include the extension in the descriptor... but when I build it with the extensionid in the xml, I just get a black screen. I am 99% sure that the extension context in the ext object is null (because that is what happens when I run it in flash debug without the extension lines in the xml)
And here I am stuck.
Can anyone tell me what I am doing wrong or what I have forgotten to do?
Thanks.