From Blue Mars Developer Guidebook

This page is protected and certified by Avatar Reality Inc. Only Editable by Avatar Reality Staff Members.

Contents 1 Overview 1.1 Scaleform 1.2 Example 1.3 Limitations 1.4 Resources 2 Getting Started 2.1 Creating a Flash File 2.1.1 Dynamic Text 2.1.2 Background 2.2 Loading a Flash File 2.3 Showing a Flash File 2.4 Positioning and Scaling 2.5 Ordering 3 Interaction 3.1 Mouse Input 3.1.1 Hiding Cursor 3.2 Key Input 3.3 Modal 3.4 Masking Mouse Events 3.5 Invoking Actionscript 3.6 FSCommands 3.7 Actions 4 Utilities 5 Debugging 5.1 Text 5.2 Background 5.3 Console 5.4 Profiler 5.5 Log

Overview

Scaleform

CryEngine 2 uses Scaleform to render Flash movies as user interface elements. The current version of Scaleform used in Blue Mars is update to the latest available (Scaleform 3.1) and made available for control via Lua scripts. Scaleform is also used to implement Flash materials

Adding a HUD to your minigame involves creating one or more Flash movies, then loading, positioning and interacting with them using Lua functions provided by Avatar Reality.

All of the HUD Lua functions are in the HUD table.

See the Flash in Blue Mars for an overview of other Flash technologies.

Example

As an example, this script brings up a pop-up dialog, waits for the Actionscript message that indicates a button has been clicked, then goes to the next state and hides the pop-up.

NEWCOExample.Init =
{
  OnBeginState = function(self)
    ...
    HUD.ShowFlash(self.Hud.confirmpopup);
    HUD.Modal(self.Hud.confirmpopup);
    HUD.AddFSCommandListener(self.Hud.confirmpopup,self.id); 
  end,
  OnFSCommand = function(self,command,arg) 
    if (command == self.FSCommands.popup_yes) then
      self:GotoState("Start");
    elseif (command == self.FSCommands.popup_no or command == self.FSCommands.popup_x) then
      self:GotoState("Finish");
    end   
  end,
  OnEndState = function(self)
    HUD.Modeless();
    HUD.HideFlash(self.Hud.confirmpopup);
    HUD.RemoveFSCommandListener(self.Hud.confirmpopup,self.id);
  end,
}

Another sample can be found in the Basic HUD Example which includes related Actionscript.

Limitations

Scaleform can load the latest Flash 8 format, however, only a few of the new SWF v8.0 features are supported, namely the common HW oriented color combines Add, Subtract, and Multiply. Most of Flash 6 and many Flash 7 features are supported. ActionScript support is limited to Actionscript 2.0.

Scaleform does not support:

• audio
• video
• HTML stylesheets
• printing
• Actionscript 3
• Actionscript web API (getURL and NetConnection)
• Actionscript garbage collection
• standard Flash components

As an alternative, you can use the regular Flash player via the FlashOverlay feature, which places a Flash player window on top of the Blue Mars client. You trade off the tighter engine integration (the HUD Lua functions listed below) for more Flash features. Compare this page with the Flash Overlay Quick Start.

Resources

• Actionscript Learning Guide

Getting Started

Creating a Flash File

For use in the HUD, Avatar Reality supports Flash files created with Adobe Flash. To create a Flash file for use in Blue Mars, create the project as a Flash 8 (or lower version) and Actionscript 2 project.

Dynamic Text

For dynamic text, you need to embed the font in the movie (the Embed button in the dynamic text Properties panel lets you select which set of glyphs to embed). Note: Don't use kerning ("Auto kern") or letter spacing (value other than "0") or Flash may render the text as HTML, causing some glyphs to display as squares.

For non-embedded font references, as with regular Flash players, Blue Mars will try to find a matching device font, but if nothing is available, blank rectangles will be shown as the font glyphs.

Background

Scaleform treats the Flash movie background differently from the foreground. The background can have its alpha (transparency) adjusted - by default it is fully transparent.

For example, this skip button movie, as seen in a regular Flash player, has the surrounding background color set to white, but that area will be transparent when viewed in a Blue Mars HUD.

The function SetFlashAlpha can be used to change the background transparency.

Loading a Flash File

Before anything can be with the HUD, the system HUD object must exist.

IsAvailable()

check if the HUD is ready to be used

HUD elements are Flash movies, in particular, swf or gfx files. In the following Lua API, HUD elements are referred to by name. The names are arbitrary strings and supplied to LoadFlash or default to the movie pathname.

LoadFlash(movie, name)

load a Flash movie

UnloadFlash(movie)

remove a Flash movie

IsFlashLoaded(movie)

check whether movie has been loaded

ReloadFlash(movie)

reload a Flash movie

Showing a Flash File

After loading, the Flash movie is not visible, yet. You can show or hide the movie at any time.

ShowFlash(movie)

make the movie visible

HideFlash(movie)

make the movie invisible

IsFlashVisible(movie)

Positioning and Scaling

DockFlash(movie, position)

specify positioning of a Flash movie

SetFlashPos(movie, x, y)

specify the movie position when DockFlash is called with eFD_Pos

GetFlashPos(movie)

get the position of a movie

SetFlashScale(movie, scalex, scaley)

set the scale of a movie

GetFlashScale(movie)

returns two values, the x and y scale of the movie

Ordering

Flash files are maintained internally in a list. Each time a Flash file is loaded via HUD.Load or HUD.Reload it is placed at the end of the list. The Flash files are rendered every frame in their order in the list, so if there are any overlapping Flash files, the files later in the list will be rendered on top. For example, if the following two movies overlap:

HUD.LoadFlash("movieA.gfx");
HUD.LoadFlash("movieB.gfx");

movieA will be rendered, then movieB, and in any overlapping region, movieB will cover movieA.

Interaction

Mouse Input

Just as with normal Flash programming, processing of mouse movements and mouse clicks for a Flash movie loaded into CryEngine is the responsibility of the Actionscript in that movie. Whereas browser-based Flash requires the browser to forward mouse events (the mouse position and mouse button clicks) to the Flash movies in a web page, Scaleform requires CryEngine to forward mouse events to any Flash movies loaded in the HUD.

For performance reasons, by default the forwarding is turned off for each movie (it's a waste to pass mouse events every frame to a Flash movie that is just a display), so for any Flash movie that must respond to mouse clicks or mouse movement, event forwarding must be explicitly enabled.

HandleFlashEvents(movie)

Specify that movie should receive mouse events

IgnoreFlashEvents(movie)

Specify that the movie should not receive mouse events

Hiding Cursor

A few developers have asked about hiding the mouse cursor. There is no function to hide the cursor (reason being that if you turn off the cursor without an obvious way for the user to turn it on again, the user is stuck, especially since Blue Mars is a windowed app). It is possible to force the cursor offscreen (with System.SetWindowMouse) which was appropriate for one special case.

Key Input

By default, Flash movies do not receive key events. Enabling/disabling key input is similar to enabling/disabling mouse input.

HandleFlashKeys(movie)

Specify that movie should receive key events

IgnoreFlashKeys(movie)

Specify that the movie should not receive key events

Modal

As in regular user interfaces, you can specify that a Flash movie is modal, i.e. no other Flash elements will receive input events. For example, a yes/no confirmation popup that must be clicked on before anything can be done would be a good candidate for a modal.

A modal movie will always receive mouse and key events, whether or not HandleEvents/HandleKeys was specified.

When a modal movie is active, the ActionMap Manager is also disabled.

Modal(movie)

Specify that the movie is modal.

Modeless()

Turns off any modal movie.

HUD.HandleFlashEvents(a);
HUD.HandleFlashEvenst(b);

both a and b will be mouse-sensitive

HUD.Modal(a);
HUD.HandleFlashEvents(b);

only a is mouse-sensitive

HUD.HandleFlashEvents(a);
HUD.Modal(b);

only b is mouse-sensitive

HUD.Modal(a);
HUD.HandleFlashEvents(b);
HUD.Modeless();

b is mouse sensitive, a is no longer modal or mouse sensitive

HUD.Modal(a);
HUD.Modal(b);
HUD.HandleFlashEvents(c);

b is modal and mouse-sensitive, c is not mouse-sensitive, a is not mouse-sensitive or modal since it was overridden by b.

Masking Mouse Events

Each movie is essentially running in a different Flash player and processes mouse events independently. So by default, for example, if two buttons overlap clicking on the intersecting region will be interpreted as a click by both.

But you can specify that mouse events that intersect a Flash movie in various ways are not passed through to movies underneath. Overlapping movies are stacked in the order they are loaded with LoadFlash.

MaskFlashEvents(movie, mask)

specifies this movie will block mouse events over underlying movies

UnmaskFlashEvents(movie, mask)

disables an event mask

IsMaskedByFlash(x, y)

check if point is masked by a Flash movie

Invoking Actionscript

From Lua, you can call an Actionscript method in a Flash movie.

SetFlashVariable(movie, path, value)

InvokeFlashMethod(movie, method, ...)

invoke an actionscript method in the movie with any number of string or number parameters

FSCommands

In Flash programming, the Actionscript function fscommand is used to invoke code in the container of the Flash movie, e.g. Javascript in a web page. The same technique is used in Blue Mars for Flash movies to communicate with entity scripts.

See the Actionscript dictionary

An entity script can listen for fscommands from a Flash movie.

AddFSCommandListener(movie, entityId)

specify that movie will send fscommands to this entity script

To actually receive fscommands, the callback OnFSCommand needs to be implemented. For example, let's say at the beginning of a state we load and display a Flash movie that receives mouse events and sends fscommands to this script:

 OnBeginState = function(self)
  HUD.LoadFlash(movie);
  HUD.ShowFlash(movie);
  HUD.HandleFlashEvents(movie);
  HUD.AddFSCommandListener(movie,self.id);
 end,

and then we define an fscommand handler within this state that will transition to another state if a certain button is clicked:

 OnFSCommand = function(self,command,args)
  if (command=="Stop") then self:GotoState("StopGame") end
 end,

Remember to remove the listener if the entity is removed.

RemoveFSCommandListener(movie, entityId)

stop receiving fscommands from movie

By default, a Flash movie will issue fscommands to the main HUD. But note that is true of a movie only if AddFSCommandListener is not called on it. These functions query the most recently issued fscommands from the Flash movies. Note that these are not preferred; they are the precursors to the recommended method of using AddFSCommandListener/RemoveFSCommandListener and the OnFSCommand callback, described above.

GetLastFSCommand()

return value - the most recent fscommand name string

return second value - the most recent fscommand argument string

ClearLastFSCommand()

when called, GetLastFSCommand() and GetLastFSArgs() return empty strings until another fscommand is issued

Actions

You can specify a callback in your entity script that responds to Actions. As shown in the examples, after registering this callback, be sure to unregister it when finished.

RegisterActionCallback(callback, entity)

UnregisterActionCallback(callback)

Actions are defined in an XML file (e.g., Game/Libs/Config/defaultProfile.xml). An example of the format is shown in this ActionMap Manager Example.

A list of keyboard and mouse action key names can be found here: List of Key Names.

These examples demonstrate Registering and Unregistering action callbacks:

• Basic ActionMap Example
• Golf

Utilities

As a convenience, Scripts/Utils/AR/ARHUD.lua defines a function that allows you to specify a number of options at once when loading a Flash file. This function also serves as an example of how to use the various HUD Flash functions.

ARLoadFlash(file, options)

Debugging

Text

Draw2DLabel(x, y, size, color, center, text)

Renders text on the screen

Background

You can adjust the transparency of the Flash movie background to see exactly how you've placed it.

SetFlashAlpha(movie, alpha)

Set the opacity of the movie background

Console

See the list of Flash console variables.

Profiler

The Flash profiler displays a list of the loaded Flash files, each with it's visibility status and time used per frame (in ms).

Use Flash Console variables to enable/disable the profiler.

Traverse the list with up/down keys and open/close each one with right/left keys to display more detailed information.

Log

Check the log for warnings and errors. For example, here's an error from an invalid path (or missing Flash movie) passed to HUD.LoadFlash:

[Error] <Flash> GFxLoader failed to open "Levels/MyCompany/Common/Libs/UI/MyFlashMovie.swf" [Levels/MyCompany/Common/Libs/UI/MyFlashMovie.swf]