Third-Party Integrations

To enable Umbra, the preprocessor definition UMBRA_ENABLE needs to be set to 1 in umbra_config.hpp in the chunk library (src/lib/chunk/umbra_config.hpp).

You will also need to add the Umbra include and library paths to your projects.

To link against the Umbra debug library, change the #pragma comment(lib, "umbra.lib") in the file (src/lib/chunk/chunk_umbra.cpp).

Umbra can run in two different modes: Hardware and Software.

The engine will choose to use hardware mode when hardware occlusion queries are supported.

In hardware mode, Umbra uses the z-buffer for occluding objects, this means that any opaque object that is rendered in the scene can occlude objects that are further away.

In hardware mode only 2 umbra cells are created, one for inside objects and one for outside objects, both cells exist in world space and are connected by umbra portals.

The BigWorld Client will chose to use Umbra in software mode when hardware occlusion queries are not supported.

In software mode only objects specified as occluders can occlude other objects. By default only terrain occludes geometry, additional static models can be set manually as occluders in Model Editor (for details, see the document Content Tools Reference Guide's section Model Editor → Panel summary → Object Properties panel). All chunk items with a physical size can be occluded by Umbra. Please refer to the Umbra reference documentation for descriptions of Umbra-related objects.

In software mode chunks correspond fairly well to Umbra cells. Each indoor chunk has a corresponding Umbra cell, which is connected to other Umbra cells by Umbra portals. All outdoor chunks share one common Umbra cell, which is owned by the chunk space. All cells exist in world space.

When using Umbra to render the scene, every ChunkItem needs to have a corresponding Umbra object. The chunk item is set as the Umbra object's user data, so that when an Umbra object is deemed visible, its chunk item can be retrieved and rendered.

When implementing a specialised chunk item, you will need to add a Umbra object for it. The chunk item contains a UmbraObjectProxy and a UmbraModelProxy, which can store the Umbra object and Umbra model for the specialised chunk item. The object-to-cell matrix is the world transform of the object.

To ease handling of Umbra objects, BigWorld Technology provides proxy objects for Umbra objects (class UmbraObjectProxy) and Umbra models (class UmbraModelProxy). These objects are a thin wrapper around the corresponding Umbra objects, allowing BigWorld Technology to use standard smart pointers to reference them.

The proxies are also stored in a managed list, to ensure that all Umbra objects are destructed before Umbra is shut down. For details on these classes, see the C++ API documentation.

Scaleform GFx is a third party Flash rendering library produced by Scaleform (http://www.scaleform.com/). Scaleform is not provided as part of the BigWorld Technology license and needs to be licensed seperately if required.

BigWorld Technology is integrated with Mozilla using llmozlib which allows showing web pages and Flash movies as part of the game but this solution is less efficient than Scaleform and therefore not suitable for game user interfaces.

Scaleform provides a hardware accelerated renderer for Flash movies suitable for use in games. BigWorld has implemented an integration with Scaleform allowing Flash movies to be displayed, and controlled by Python.

Scaleform IME is an optional add-on for Scaleform customers, allowing display of an in-game Scaleform IME movie to replace the windows IME language bar. BigWorld has integrated against Scaleform IME as well.

While Scaleform has tried its best to optimise rendering of Flash movies, there are still a number of guidelines that artists should follow in order to create Flash movies that behave well and don't bog down performance unnecessarily. It is therefore essential that you read the appropriate Scaleform documentation before launching into full-scale production of Flash movies for use with your BigWorld game.

This document describes how to display and use a Flash movie in BigWorld. It describes the changes required to the client to build in the Scaleform integration. It then describes how to use the Python API to display and manipulate a Flash movie. Finally it describes some BigWorld-specific features and limitations.

In order to build the client with support for Scaleform, you must download and install the SDK (version 3). The installer will create an environment variable called GFXSDK which is used by the BigWorld client solution to locate the SDK installation. You can check that the environment variable is correctly set by opening a command prompt and entering the command set GFXSDK. It should print out the root installation path of the Scaleform SDK.

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

This section aims to show you how to load up a Flash movie and display it in your game's user interface.

# 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 )

#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

<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>

No doubt you will want to build complex UI's in Flash that interact with your BigWorld game, sending and receiving events and swapping data back and forth. All method and data interactions are handled via the PyMovieView Python object. This chapter details a number of different ways to interact with your Flash movie and its action script.

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

movieView.setFSCommandCallback( myFSCommandHandler )

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 )

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

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

BigWorld's source code ships with support for SpeedTreeRT 4.2 turned off by default. A few steps need to be followed in order to enable support in the game client and tools:

For a SpeedTree to be available in World Editor, or to be loaded from a chunk file into a space within the game client, the following resource files need to exist in the resources tree:

For each tree, these files should reside in the same folder. More than one tree can coexist in the same folder, as long as no filename clash occurs.

For performance reasons, we assume that all trees use a composite map for the frond, leaf, and billboard textures. For details on how to have a tree to use composite maps, see the SpeeTreeCAD's User Manual.

To take advantage of SpeedTreeCAD's alpha noise cross-fading feature (a fundamental feature which use we highly recommend), you will also need an accompanying .texformat^[1] filefor the composite texture map, or an appropriate wildcard entry in <texture_detail_levels>.xml. For details, see Level of detail.

Optionally, you can have a SpeedWind.ini file in this same folder if you require finer control over how this tree wind animates. For details, see Wind animation.

Once the resource files are in place, trees are ready to be used within World Editor. To insert a tree, either drag a .spt file from the Asset Browser panel^[2] into the viewport, or select the desired .spt file and press Enter.

Once a tree has been added, it can be selected, moved, rotated, and scaled like any other model in World Editor. You can do this interactively (see Mouse controls) or by editing the trees' properties in the Properties panel (see Properties panel). In the Properties panel, you can also edit the name of the .spt file and the seed number used to generate the tree geometry. The results of editing a tree's properties can be immediately previewed in the viewport.

If a tree cannot be loaded during chunk loading then a red box model will be rendered in its place. The box can still be manipulated and most of its properties edited with the exception of its seed. Any changes will be saved and restored if that tree is loaded in the future.

BigWorld uses SpeedTree's new SpeedWind library to animate trees swaying to the wind. SpeedWind's parameters can be tuned and previewed from within SpeedTreeCAD, and then saved as a .ini file. This file can then be loaded into BigWorld's 3D engine to control how trees animate.

A global .ini file is used by default for all trees. Optionally, a unique SpeedWind.ini file can be tied to a specific tree, by placing it in the same folder as the .spt file (the name of the file is required to be SpeedWind.ini). If neither file is present, then SpeedWind's engine will be setup with its default parameters.

Although SpeedWind's parameters define how a tree should animate given a wind of certain direction and strength, the actual wind's direction and strength fed into SpeedWind's engine is provided by BigWorld's dynamic weather system, conveying a convincing and immersive experience for the player.

BigWorld's 3D engine fully supports SpeedTree's LOD model. Branches and fronds switch detail levels discretely, while leaves and billboards LODs cross-fade according to the distance to the camera.

By default, the actual LOD level of a tree — a value that ranges from 0 (minimum detail) to 1 (maximum detail) — is a linear function based on the distance from the tree's origin to the camera's eye position. The lodFar and lodNear parameters define the distance interval within which the trees' LOD levels will vary. In the default LOD mode, the LOD function is the same for all trees.

Optionally, you can rely on SpeedTree's engine to compute the LOD level for each tree based on parameters contained in the .spt file (which can be edited from SpeedTreeCAD). Roughly speaking, they work in the same way as explained above, but with specific near and far values for each tree. This allows a more fine-grained control of LOD transitions, and a better match between what is previewed on SpeedTreeCAD and what is rendered on the tools and the client. The only drawback is that relying on SpeedTreeRT for the LOD computation is a bit slower than letting BigWorld do it.

You can switch between this two LOD modes by editing the lodMode parameter in SpeedTree's XML file (for details, see XML file) or interactively, via watchers (for details, see Watchers). The parameters lodNear and lodFar are also accessible this way.

The lodOverlap parameter defines how much overlapping should happen during the cross-fading of LOD levels. The valid range goes from 0 to 2. The default value is 1. This parameter is also accessible via XML file and watchers.

Leaves and billboards, when phasing in or out their LODs, cross-fade their alpha test values in order to smooth level transitions. This technique requires composite texture maps with homogeneous noise baked into the alpha channel and pre-generated mipmaps. Also, BigWorld's auto mipmapping generation should be disabled for this texture map.

To disable the automatic generation of mipmaps in BigWorld, you will need to setup a .texformat^[3] file for each tree's composite texture map, which is illustrated below:

<root>
  <mipCount>       -1    </mipCount>
  <horizontalMips> true  </horizontalMips>
  <mipSize>        0     </mipSize>
</root>

Example .texformat file

The example above configures the following:

A more general way of achieving this is by adding a wildcard entry to <texture_detail_levels>.xml. The entry should match all composite maps used by SpeedTree, and define the same attributes shown above. An example of a wildcard entry is illustrated below:

<detailLevel >
  <prefix>         speedtree </prefix>
  <contains>       composite </contains>
  <mipCount>       -1        </mipCount>
  <horizontalMips> true      </horizontalMips>
  <mipSize>        0         </mipSize>
</detailLevel >

Example <texture_detail_levels>.xml entry

For details on how to create texture maps with alpha noise and pre-generated mipmaps, see SpeedTreeCAD' User Manual.

The first time a tree is loaded, BigWorld uses the collision geometry specified in the .spt file to generate the BSP trees that will populate the collision scene in a space. In the game client, you can preview these BSP trees by enabling the SpeedTree/BSP watcher (for details, see Watchers). In World Editor, enable the General Options panel's Show list box's Scenery → BSP item (for details, see General Options panel).

If the engine has write access to the resource path, then a cache of the BSP tree will be saved, to speed upload time in the future. This cache file will be re-created whenever the .spt file is modified.

Once a tree's BSP tree has been inserted into the collision scene, it will be used in all collision queries in the engine, including line-of-sight, navigation paths generation, static lighting, and more. When loaded from within World Editor, if a tree has no collision geometry defined, then a temporary BSP tree in the shape of a box will be created, to allow the world builder to select and interact with the tree. This temporary BSP tree is not cached, and will not be created when the tree is loaded into the game client.

For details on how to define a tree's collision geometry, see SpeedTreeCAD's User Manual.

Normally, the server is not built to use SpeeTreeRT, and requires the BSP files to be present in the resource path in order to load SpeedTrees into the collision scene. The recommended approach is to check all SpeedTree BSPs into the repository so that they will be accessible to the server. When running the server, if the associated BSP file is not available when loading a SpeedTree, then it will fail to load (the chunk will be loaded successfully, though).

All game-specific settings related to rendering SpeedTrees are defined in a XML file, which actual name is defined in resources.xml (for details, see the document Client Programming Guide's section Overview→ Configuration files → File resources.xml) , under the system/speedTreeXML tag, and defaults to speedtree/speedtree.xml.

This file is read upon initialisation of BigWorld's 3D engine. For details on these tags, please see inline comments in fantasydemo/res/speedtree/speedtree.xml.

In both the game client and World Editor, several watchers (for details, see the document Client Programming Guide's section Debugging → Watchers) are available to instantly customise and debug the behaviour of SpeedTrees.

The list below describes them (all watchers listed are prefixed by SpeedTree/):

The watchers LOD Mode, LOD Near, LOD Far, and LOD Overlap are read from SpeedTree's XML file when the engine is initialised. Modifying them via WebConsole's ClusterControl module (for details, see the document Server Operations Guide's section Cluster Administration Tools → WebConsole) does not modify the contents written into the file.

The list below describes some errors that you might come across when implementing SpeedTree:

To implement sounds in your game, an FMOD sound bank needs to be created using the FMOD Designer tool. A very small example sound bank project is provided, and is located at fantasydemo/audio/fd_sound.fdp. Please see the documentation for FMOD Designer for details on how to create and edit your own sound banks.

Sound banks must be specified in the engine configuration XML file. Multiple sound bank projects can be specified, and can be configured to load on client startup or only by request from the scripts. See Sound Engine Configuration for more detail on this.

BigWorld provides easy to use functions for playing back sound events defined by the FMOD Designer tool.

See the Client Python API documentation for more details on these functions and the FMOD.Sound object.

NVIDIA provides a tool called oaman which allows setting specific game settings and running tests. The oaman tool is available in src\lib\third_party\openautomate\oaman\oaman.exe.

Using oaman can be done as follows:

Running nightly testing to detect performance degregations and stability issues is a recommended practice for game development. The BigWorld Technology Client can read and execute open automate commands (and additional commands) based on xml files provided as part of a command line. Following is the syntax for running a test using an xml instructions file:

<BigWorld Technology Client> -openautomate INTERNAL_TEST <text xml file>

For example:

bigworld.exe -openautomate INTERNAL_TEST \
	<fd res>\scripts\testing\openautomate\simpleSetAutoDetect.xml

The above example illustrates how to auto detect the client settings and use the highest video mode. Please refer to the corresponding

currentCommand == "CMD_AUTO_DETECT" 

in OpenAutomate.py to understand the implementation. This command should be used before running other tests to make sure that we are using the same graphics and video settings when running tests.

Running the command:

bigworld.exe -openautomate INTERNAL_TEST \
	<fd res>\scripts\testing\openautomate\testAdvancedRunBenchmarks.xml

will run multiple benchmarks and quit.

Customers wishing to add more tests can add logic to the OpenAutomate.py file. The function testOAGetNextCommand() available at src\lib\open_automate\open_automate_tester.cpp contains the implementation which reads the xml files and sends commands to the OpenAutomate.py file. Changing this function might be required for advanced customers wishing to add additional testing capabilities to their xml files.