The Scaleform integration library is included with your BigWorld Technology package in the bigworld/src/lib/scaleform directory. Contained in this directory is a file called config.hpp, which should be changed to look like this:

#define SCALEFORM_SUPPORT 1
#define SCALEFORM_IME 1               //only necessary if also using Scaleform IME

Then rebuild the client. That's all you should have to do.

Flash movies are integrated with the BigWorld GUI system. This allows you to, for example, embed a Scaleform movie within a moveable window, or to pop up a Scaleform movie like an Inventory display in the HUD.

In order to do this, you simply wrap the MovieView object in a Flash GUI Component. Once you do this, the GUI object takes control over the lifetime, display, size, position and input handling for your movie.

# movieDef, movieView attributes created in the above example

import GUI
g = GUI.Flash( movieView )
GUI.addRoot(g)

# movie is now displayed via the GUI tree, instead of displayed via a global Scaleform movie list.

# The movie can now be positioned just like other GUI components.
g.position = (1.0,-1.0,0.6)
g.verticalAnchor = "BOTTOM"
g.horizontalAnchor = "RIGHT"
g.widthMode = "PIXEL"
g.heightMode = "PIXEL"
g.size = (256, 256)

# The movie now responds to key / mouse events just like other GUI components
g.focus = True             # respond to key events
g.mouseButtonFocus = True  # respond to mouse button events
g.moveFocus = True         # respond to mouse events

class MyFlashScript( object ):
    def __init__( self, component ):
        self.component = component
        component.script = self

    def handleKeyEvent( self, event ):
        if event.key == Keys.ESCAPE:
            self.visible = False
            return False
        
        return self.component.movie.handleKeyEvent( event )    
        
    def handleMouseButtonEvent( self, comp, event ):
        self.component.movie.handleMouseButtonEvent( event )
        return self.component.movie.hitTest( event.cursorPosition )

    def handleMouseEvent( self, comp, event ):
        self.component.movie.handleMouseEvent( event )
        return self.component.movie.hitTest( event.cursorPosition )

In the above example, two objects were created, a Movie Definition and a Movie View. Both of these are Python objects that internally maintain a reference to one or more Scaleform C++ objects. As a game programmer, all you need to know is that as long as you keep your Python objects alive, the underlying Scaleform objects are kept alive too. Here's a code snippet that demonstrates the lifetime of these two Python objects :

#movieDef, movieView attributes created in the above example

# First we will free the movie definition.
del movieDef

# The Movie View will still play, however in future if you require a new view of that movie, you'll have to reload the entire movie.

# Now free the movie view.
del movieView

# Notice that deleting the movieView object means it is no longer displaying

If you hold onto Scaleform objects after the Personality Script is fini'd(), then you will run into problems, as the Scaleform subsytem is shut down before Python. When Python is shut down, it frees all its outstanding objects, and the Python-controlled Scaleform objects will be released too late, causing an assert. It is up to you to make sure you release these objects before shutdown.

The BigWorld Scaleform integration allows you to specify where fonts are loaded from by creating a font configuration file that sits next to the source .swf. This file allows you to specify any number of additional SWF filenames which will be searched by the Scaleform loader for fonts, and it allows you to define any number of font mappings. Internally, this corresponds to GFxFontLib and GFxFontMap respectively.

For example, if a movie is located at res/scaleform/mymovie.swf, the font configuration file would be named res/scaleform/mymovie.fontconfig. To avoid duplicating the same font configuration, it is possible to create a default.fontconfig and this will be used if a specific font configuration is not found (this is unique per directory).

The font configuration file is an XML file and has the following basic layout,

<root>
    <lib> fontlibA.swf </lib>
    <lib> fontlibB.swf </lib>
    ...
    <lib> fontlibX.swf </lib>

    <mapping> $FontNameA
        <family> Times New Roman</family>
        <flags>  BOLD </flags>
        <scaleFactor> 1.7 </scaleFactor>
    </mapping>

    <mapping> $FontNameB
        <family> Arial Unicode MS </family>
        <flags>  NORMAL </flags>
        <scaleFactor> 1.3 </scaleFactor>
    </mapping>
    ...
    <mapping> $FontNameX
        <family> Arial </family>
        <flags>  ITALIC </flags>
        <scaleFactor> 1.0 </scaleFactor>
    </mapping>
</root>

See the Fonts document in the Scaleform GFx SDK for details on how fonts work inside Scaleform.

In earlier versions of Action Script, the fscommand() call was the way to call out from Action Script and into its container. fscommand() is supported by Scaleform and BigWorld. In order to handle fscommand() calls, you simply register a Python callback function to handle any such calls :

def myFSCommandHandler( cmd, arg ):
    # cmd, arg are both strings.  Dispatch to wherever is appropriate.

movieView.setFSCommandCallback( myFSCommandHandler )

In later versions of Action Script, external interface is used instead to call out of Action Script and into the containing application. External Interface calls have the advantage of allowing different types and number of arguments to be passed around (instead of fscommand supporting only a single string argument). Additionally, the container can set return values for the external interface call. Usage is similar to handling fscommand, however the callback function has a different interface :

def myExternalInterfaceHandler( cmd, *args ):
    # cmd is still a string, but now we have a list of arguments, with arbitrary types.  Dispatch to wherever is appropriate

movieView.setExternalInterfaceCallback( myExternalInterfaceHandler )

Action Script variables tend to be buried in a hierarchy, often looking like : "_root.levelN.someVariableName". Unfortunately this syntax is misinterpreted by Python and currently there is no elegant solution to work around this. However it is still easy to exchange data with Action Script. All that is required is to use Python's setattr and getattr syntax. For example:

setattr( movieView, "_root.level0.maxHealth", 10 )
currentHealth = getattr( movieView, "_root.level0.health" )

Using this syntax you can get and set any of the following types of data : boolean, int, floats, string and unicode string.

The final interaction you will want to have with your Flash movie is to call Action Script methods directly from Python. In order to do this, simply use the invoke() method:

result = movieView.invoke( "_root.level0.flashHealthBar", 10.0 )