I have been working with U3DObject for a a few weeks now and have been getting familiar with it. Because there is so little documentation with it, it is a little hard to figure out how everything works and is organized. The company that created this isn’t an English company, so some of their English is a little bit hard to interpret in their documentation. In this post, I will try to explain the structure of the U3DObject framework as well as talk about the API. A small stripped down demo project was made to better help understand the concepts. Take a look at the demo project that I will be going over.
Where to start?
Folder Structure and organization
If you open up the BasicExample folder, you will see three sections: flash, html, and unity. The flash and unity sections have the source files that will have the different assets and scripts needed to build the swf and unity3d files. These folders are where you will spend most of your time in. The html section has the final web files that will be uploaded to the server. I set the system up so that when you publish your flash files, it will export to the swf folder of the html section. Likewise, when you build your unity3d application, you will build it in the unity folder of the html section.
The two things that take time to learn are the two APIs for Unity and Flash. With a little help and the sample file, hopefully it won’t take too long.
Flash as a foundation
One thing to know right away is that flash is controlling the show with this framework. If you load the page, Flash starts up and Unity is no where in sight. You can load, hide, show, send events, function and more through Flash. The project can show you some of the commands that will be sent. For Flash to communicate to Unity, it has an API written that is called ExternalInterface. Through this API, you can do what you need to do. Here are the API calls you can do with a short description. The APIs are also in the project files oustide of the three sections.
Flash ExternalInterface API
initialize ( maxTimeOut:int):bool
Initializes the interface. Required to start before you do anything else. Checks if Unity and ExternalInterface are available in the page. Second inititialize constructor with no paramaters uses a default value of 5 for the maxTimeOut.
addEventListener ( callFunction:function):void
Adds a listener for UnityInterface events. callFunction gets called when Unity sends an Event to Flash.
removeEventListener ( callFunction:function):void
Removes a listener for UnityInterface events.
dispatchEvent ( eventName:String, parameters:* ):void
Dispatches a UnityEvent within Flash. No external communication is done with this.
dispatchUnityEvent(eventName:String, parameters: *, unityCSSID:String):void
Dispatches an event inside the unity ‘ExternalInterface’ game object, calling the function ‘OnExternalEvent’. You need to have an addListener attached to the Unity gameobject script for this to register
embed( width:Number, height:Number, fileName:String, unityCSSID:String):bool
Embeds the unity in the div and starts its download.
call(functionName:String, gameObject:String, unityCSSID:String):void
Calls a Unity method within the application with the format ‘function_name(params …)
functionName: Function to call in the format ‘function_name(params …)’
gameObject: Unity game object in the application that has the function being called.
UnityCSSID: Div inside the HTML that contains the Unity application.
Shows the Unity application in the page.
Hides the Unity application in the page.
Flag that indicates the presence or absence of the Unity webplayer.
Link to the Unity webplayer installer for the platform running the swf.
Additional Notes about Flash
some of the parameters like unityCSSID and gameObject are stored in variables in the flash file, so they can be switched easily. The actionscript is commented fairly well, so you can see what is going on. I tried to keep it pretty simple and contained with each function. Before looking at it too much, it would be good to look at the Unity script and API to see how things are received and sent on the other side. Onwards!
Unity3D ExternalInterface API
As you can expect, there is a Unity ExternalInterface class that performs similar actions. Since Unity doesn’t have that much control, there are less things that it can do to flash. Here is the list.
AddListener ( ExternalEventListener listener)
Adds an event listener to this interface, so you will be able to receive External Events.
RemoveListener ( ExternalEventListener listener)
Removes an event listener to this interface, so you will stop receiving events from the class
DispatchFlashEvent( string flashID, string event, params object sendingparams)
DispatchFlashEvent( string event, params object sendingparams)
Calls the specified flash function (listen to an OnUnityCall event inside your flash). Second function is used if ExternalInterface initialized the flashID already.
LoadProgress( string flashID, float progress)
LoadProgress( float progress)
You must actively call this method to inform external listeners (outside Unity) how is the loading progress of your game going. Second function is used if External Interface initialized the flashID already.
You must actively call this method to inform external listeners (outside Unity) that your game have finished loading. econd function is used if External Interface initialized the flashID already.
This method will initialize the externalinterface. You must call it before you can start receiving external events. FlashID in the second function is used to identify flash when calling it.
Note: Unity will create a Gameobject called “ExternalInterface” and attaches the ExternalInterface script when you use this method. Also, when you call this while providing the flashID, you can use a lot of the other calls that don’t require the flashID as a parameter. The class stores it in the ExternalInterface as a static variable.
Method called by the U3dObject proxy (JS outside Unity). Remember to attach an instance of this class to your scene. Params is the data coming from external side (see u3dobject.js)
Unity3d ExternalInterface Notes
You can take a look at the C# or actionscript files in the project to understand it better. Let me know is anything is unclear or I left anything out!
I have been looking and doing a lot of programming, so I think I will take a little break and do more art related things. Maybe some concept art. I have been reading some articles on better ways to do texturing, so eventually the art might turn into 3d models. I need to beef up my portfolio a little more this year, so maybe adding some 3D work would be good.