Overview
Adobe Flash's recent effort on FlasCC compiler makes native code running on web browser possible. The Stage3D technology also provides a fully hard-ware accelerated architecture that brings visuals across browsers. With these, SmartBody now can run as a standalone application on browsers that has latest flash plugin properly installed.
Using FlasCC, SmartBody will be compiled into a static library that can be linked by other application. SmartBody has a simple rendering application distributed in repository, if more complicated requests are needed, you can choose to use game engine that has FlasCC integrated. The best integrated engine is Unreal Engine3, following link shows its capability http://www.unrealengine.com/flash/.
Here are the link to our simple flash demo demonstrating the basic capabilities:
http://smartbody.ict.usc.edu/HTML/videos/flascc/SBFlashDemo-ChrBrad.mp4
http://smartbody.ict.usc.edu/HTML/videos/flascc/SBFlashDemo-doctor.mp4
Requirements
You need to download the latest Flash C++ Compiler(FlasCC SDK) from https://www.adobe.com/products/gaming/tools.html, registration will be needed to get into downloading page. If you want to compile samples that comes with FlasCC, you also need to download Flex SDK at http://www.adobe.com/devnet/flex/flex-sdk-download-all.html. You can find FlasCC documentation from http://www.adobe.com/devnet-docs/flascc/. Following are the instructions of setting up FlasCC.
| Installation Step | Windows | Mac |
|---|---|---|
| 1 | Exact the contents of the FlasCC zip file onto anywhere on your hard drive. | Extract the contents of the FlasCC DMG file onto your hard drive |
| 2 | Ensure 64-bit Java is installed and Java is on your PATH and pointing to the right directory (so it doesn't confuse with other version you have on your machine) | Ensure 64-bit Java is installed |
| 3 | Exact Flex SDK to anywhere on your hard drive | Exact Flex SDK to anywhere on your hard drive |
| 4 | Lauch run.bat under FlasCC folder, this is the cygwin environment where all the compiling happens | Launch terminal and get ready to compile |
Make sure you also get a debugger for flash player from http://www.adobe.com/support/flashplayer/downloads.html both on Windows and Mac.
Compiling and Running
The first thing to do is to change tool chain by adding sdk/usr/bin folder to the head of your path like following (change the path accordingly to your flascc directory):
Mac> export PATH=~/flascc/sdk/usr/bin:$PATH Win> export PATH=/cygdrive/c/flascc/sdk/usr/bin:$PATH
Second, create a local directory under flascc/sdk/usr so all the third party libraries will be installed there.
Repository files layout
All the files related to flash compiling are under trunk/flash.
- actionscripts: contains all the actionscripts related to console and preloader.
- cmakefiles: contains all the cmake files needed to compile SmartBody and minimal flash demo.
- data: gives an example of how assets would be assembled.
- demo: contains the complete built minimal smartbody flash demo.
- install: includes all the pre-built third party libraries and actionscripts.
- minimalflashapp: inside is the .cpp file for minimal flash demo, it's based on the simplesmartbody.cpp, also export.txt that contains compiling symbols.
- mms.cfg: this file is used to override flash setting on your local machine.
How to use these files are explained in the following sessions.
Compiling Third Party Libraries
You can choose to use pre-built third party libraries from /trunk/flash/install folder, just manually copy them under your /flascc/sdk/usr/local. If you decide to build your own, following are the steps:
| Third Party Libraries Compiling | |
|---|---|
| 1 | compiling xerces-c Download xerces-c-3.1.1.tar.gz from http://xerces.apache.org/xerces-c/download.cgi ./configure --disable-shared --disable-network --prefix=/flascc/sdk/usr/local make make install |
| 2 | compiling python 2.6 Download Python from: http://www.python.org/download/releases/2.6.8/ ./configure --disable-shared --without-signal-module --prefix=/flascc/sdk/usr/local make make install During compiling you will meet some errors, following is the changes needed to make. ./Modules/posixmodule.c: change I_PUSH to TIOCPKT ; include<sys/ioctl.h>; define out BSD block that contains fpgetmask Inside Makefile: get rid of build interpreter. Python will be installed but the interpreter won't be working correctly and there's trouble setting Py_Home |
| 3 | compiling boost Download Boost from: http://sourceforge.net/projects/boost/files/boost/1.44.0/boost_1_44_0.tar.gz/download add $TOOLSETROOT to bootstrap.sh at the top change ./build.sh "$TOOLSET" to ./build.sh "$TOOLSET" "$TOOLSETROOT" ./bootstrap.sh --prefix=/flascc/sdk/usr/local ./bjam ./bjam install |
| 4 | compiling ODE Download ode-0.11.1 from:http://sourceforge.net/projects/opende/files/ ./configure --prefix=/flascc/sdk/usr/local make make install |
| 5 | compiling GLS3D (OpenGL For Stage3D) Download GLS3D code from https://github.com/adobe/GLS3D. make FLASCC=/flascc/sdk manually copy the include and lib to /flascc/sdk/usr/local More details about use of GLS3D can be found at http://www.adobe.com/devnet/games/articles/compiling-opengl-games.html |
| 6 | compiling alcfreeglut (freeglut2.8.0 ported to Flash with FlasCC and Stage3D) Download glut code from https://github.com/alexmac/alcfreeglut make FLASCC=/flascc/sdk GLS3D=/path/to/GLS3D manually copy the include and lib to /flascc/sdk/usr/local |
Compiling PreLoader and Console
Console class is the first class that is created and executed when SWF loads, it controls when and how the FlasCC compiled code is initialized and executed.
FlasCC compiled code starts executing when the whole SWF file has been loaded in the browser, it's a best practice to show some kind of loading screen before then. Default PreLoader.swf shows a black screen with a whilte loading bar that progresses across the screen as the SWF loads.By using HTTP VFS, the zipped data folder will be downloaded during the pre-load.
From your console, navigate to trunk/flash/actionscripts folder, do following command to compile console.abc, PreLoader.swf
make FLASCC=/flascc/usr/sdk
Compiling SmartBody and Minimal SmartBody Flash Application
First, copy all the cmake files from trunk/flash/cmakefiles to the corresponding locations, it should be straightforward by looking at the directory layout.
Second, generate the Makefiles with cmake:
mkdir builddirectory
cmake ..
Third, copy simplesmartbody.cpp from trunk/flash/minimalflashapp to trunk/core/smartbody/simplesmartbody, overriding the original one. Copy exports.txt from trunk/flash/minimalflashapp to trunk/<builddirectory>/core/smartbody/simplesmartbody. Copy built Console.abc and PreLoader.swf from trunk/flash/actionscripts to trunk/<builddirectory>/core/smartbody/simplesmartbody.
Go to the build directory, make and install the applications
cd builddirectory
make
After make, smartbody-lib.a, smartbody-dll.a and simplesmartbody.swf will be generated.
Compressing Data for Minimal SmartBody Flash Application
You need to zip all the files inside data folder and copy it to trunk/<builddirectory>/core/smartbody/simplesmartbody. Data folder has to follow some standard hierarchy so that application can be launched properly. You can check out an example data folder from trunk/flash/data. Following are some notes for data folder layout.
- data.zip should not contain a data folder. It should contain everything under it.
- it has to have a sbm-common/scripts folder where inside that folder default-init.py will be the startup script.
- at top folder, you will see two .txt files. AnimationList.txt and XMLFileList.txt. AnimationList.txt contains a list of animations that later on one of them will be random picked and played inside application. XMLFileList.txt contains a list of sound files (without extension), one of them will also be random picked.
If you have sound files, it doesn't need to be zipped. You will need to convert them into .mp3 format and put them under the same directory of your final swf.
Running Minimal SmartBody Flash Application
After finishing above steps, you will see a minial smartbody flash application generated under trunk/<builddirectory>/core/smartbody/simplesmartbody.
You can run your flash debugger and drag drop simplesmartbody.swf to it. Another way is to launch SmartBodyDemo.html in various web browser.
Make sure you applies mms.cfg to your local flash setting which extends the ScriptStuckTimeout. You can find mms.cfg from trunk/flash
| Windows 32-Bit | %systemroot%\System32\Macromed\Flash |
| Windows 64-Bit | %systemroot%\SysWOW64\Macromed\Flash |
| Mac | /Library/Application Support/Macromedia |
Notes
- While extracting library under Windows, make sure to use 7-zip instead of Winzip. Winzip extracted files will have format issues with files constructed on *nix system.
- gcc compiler sometimes doesn't like cygwin's way of defining directory. So if "/cygdrive/e" doesn't work, try "E:/"
- While compiling large 3rd party libraries, it sometimes take a lot of memory on java virtual machine. If memory is not assigned enough, it would throw out an exception. To avoid that, passing in a CFLAGS -jvmopt=-Xmx6000M.
- The reason of mms.cfg existing is because the computation cost of SmartBody. Sometimes function overhead is bit big so it takes more than 15 seconds to execute so it would trigger default flash timeout exception. To fix that, SmartBody codes need to be more optimized.
- With different experiments i prefer building 3rd party libraries using Mac and building SmartBody with Windows under Cygwin. Advantages of using Cygwin: fast, you can assign more java virtual machine memory on windows(more often windows has better configuration than mac book). Downsides of Cygwin: sometimes you will find weird compiling errors with 3rd party source codes.
- The assets used for FlasCC SmartBody has to be optimized so that application can run at 60 fps (mainly mesh and texture resolution).
- The minimal application is a combination of c++ native code, flash++ API and action scripts.
- Make sure if you run on web browser, its flash plugin is update to date and properly installed.
- This is minimal version of SmartBody, so some features are disabled, including locomotion, steering, reaching.
Test, future improvements and others
Performance
With a single SmartBody character rendered with textures using CPU deformable geometry where the texture and mesh are low resolution, we are getting 60 fps.
Test running on different web browsers
| Flash Debugger | Google Chrome | Firefox | IE | Safari | |
|---|---|---|---|---|---|
| Windows | OK | __gnu_cxx::__concurrence_unlock_error | OK | OK | not supported |
| Mac | OK | __gnu_cxx::__concurrence_unlock_error | OK | not supported | OK |
Needs to look into concurrence unlock error.
Future improvements
- Python interpreter is not built correctly, it doesn't affect the usage of python in SmartBody, but it might affect use of Cerebella later on. Need to setup python home correctly so it can load the python modules.
- Some of the functions needs to be optimized or break down into fine pieces so it would not trigger flash's 15 second default timeout exception.
- CPU shading is taking up too much computing time, there's a way to use Stage3D's GPU shader language AGAL to do the mesh binding.
Embedding in Unity4
Unity doesn't support FlasCC directly so you won't be able to link your rendering application to the pre-built static SmartBody library, but theoretically you can load a swf from another swf. Construct a swf file that serves as a connector from Unity rendering application to SmartBody library should be able to achieve it.
Compare FlasCC, NaCL and Emscripten
There's other solutions besides FlasCC. NaCL https://developers.google.com/native-client/ and Emscripten https://github.com/kripken/emscripten.
Emscripten compiles native code into javascript that can be used directly inside html inside any web browser, it has a good amount support for OpenGL in a OpenGL ES standards. But it has it's limitations mostly when it comes to multi-threaded codes, full limitation can be found here https://github.com/kripken/emscripten/wiki/CodeGuidlinesAndLimitations.
NaCL compiles native code into it's own NaCL modules and talks to Browser using Pepper Plug-in API. It supports almost 3D rendering, multi-threading, audio, FileIO etc. It is actively maintained by Google. It right now has integration with Unity4 and Orge3D. Downsides is obvious, you will be only running it on Google Chrome with NaCL plugin installed.
FlasCC is developed by Adobe to compile native codes into flash. Flash has been existing for a long time thus it's well adopted by almost all the web browser, there's a lot of tools helping developing and debugging flash related application, also it already has a sound community with experienced developer. Downsides flash plugin is always needed and it has to be installed properly.