UDN
Search public documentation:

GFxUDKFrontEndGuide
日本語訳
中国翻译
한국어

Interested in the Unreal Engine?
Visit the Unreal Technology site.

Looking for jobs and company info?
Check out the Epic games site.

Questions about support via UDN?
Contact the UDN Staff

UE3 Home > User Interfaces & HUDs > Scaleform GFx > Making sense of GFx UDKFrontEnd

Making sense of GFx UDKFrontEnd


Overview


This is a step by step, high level explanation of how GFxUDKFrontEnd loads and displays each view of the menu which ships with UDK.

This simplified version illustrates the code and assets needed for pushing and popping two views (Main Menu and Options) to a view stack, using a menu manager. It contains custom files and assets (not covered below, but similar in execution).

ALERT! Note: Add the following two lines to [Engine.PackagesToForceCookPerMap] in DefaultEngine.ini.

DefaultEngine.ini
.Map=SF-FrontEnd
.Package=SFSandbox

Files Involved


Unreal Script Files Involved

  • The Menu Manager - \Development\Src\UTGame\GFxUDKFrontEnd.uc
  • The Views - \Development\Src\UTGame\GFxUDKFrontEnd_MainMenu.uc , *Multiplayer.uc, *Settings.uc, etc.
  • Base class for Views - Development\Src\UTGame\GFxUDKFrontEnd_Screen.uc
  • Base View class - \Development\Src\UTGame\GFxUDKFrontEnd_View.uc

Flash Files Involved

  • The Manager - \UDKGame\Flash\UDKFrontEnd\udk_manager.fla
  • The Views - \UDKGame\Flash\UDKFrontEnd\udk_main_menu.fla, *multiplayer.fla, *settings.fla, etc.
  • All graphical assets pulled from this file - \UDKGame\Flash\UDKFrontEnd\udk_assets.fla

ActionScript Files Involved

  • The Views - \UDKGame\Flash\ActionScript\com\scaleform\udk\view s\MainMenuView.as, MultiplayerView.as, SettingsView.as, etc.
  • The Manager - \UDKGame\Flash\ActionScript\com\scaleform\udk\mana gers\MenuManager.as
  • Utlility for registering a document's class - \UDKGame\Flash\ActionScript\com\scaleform\udk\util s\UDKUtils.as

Other Files

  • \UDKGame\Config\DefaultUI.ini
  • \UDKGame\Content\Maps\UT3\UDKFrontEndMap.udk

GFxUDKFrontEnd.uc is the master class (or manager) for the front end (menu). It is called in the startup level (UDKFrontEndMap) in Kismet via Open GFx Movie. The Movie loaded there is: UDKFrontEnd.udk_manager, and the Movie Player Class is set to GFxUDKFrontEnd. Take Focus, Capture Input, and Display With Hud Off are all checked.

  • GFxUDKFrontEnd’s SWF is defined in defaultproperties as: UDKFrontEnd.udk_manager
  • udk_manager.FLA/SWF is given the document class of: com’scaleform.udk.managers.MenuManager (MenuManager.as)
    • MenuManager.as initializes the _viewStack array and provides several functions for tweening (animating) the viewstack.
    • udk_manager.FLA contains the empty movieClip: manager which is of type: manager. This movieClip will be used to hold the views.

GFxUDKFrontEnd Call Stack


  • Creates ViewInfo data structure
    • ViewName, SwfName, and DependantViews
    • These values will be populated by data in DefaultUI.ini
  • Creates ViewData[] array of type ViewInfo
    • +ViewData lines defined in DefaultUI.ini
  • Start() is executed
    • Calls ConfigFrontEnd()
  • ConfigFrontEnd() is executed
    • “_root” of udk_manager.fla is cached in RootMC
    • “manager” from udk_manager.fla is cached in ManagerMC
  • Start() calls LoadViews()
  • LoadViews() is executed
    • Calls LoadView() passing each element (each view) of the ViewData[] array
  • LoadView() is executed
    • A new empty movieclip is created inside ManagerMC with the name: SomeViewNameContainer (example: MainMenuContainer, MultiplayerContainer, HostGameContainer, etc.)
      • And this new movieclip is referenced by ViewContainer
    • A new empty movie clip is then created inside the ViewContainer with the name: SomeViewName.
      • This new movieclip is referenced by ViewLoader.
    • We get the SWFName and store at element 0 of the args[] array of asvals as a string.
    • We then invoke “loadMovie” (a standard Flash function in a GFxObject) on ViewLoader, passing it the SWFName via the args[] array.
      • This loads the actual SWF file for that view into the ViewLoader movie clip as a new movie clip.
      • The SWF files sets their document class (example: com.scaleform.udk.views.MainMenuView (MainMenuView.as))
      • The SWFs contain an empty movie clip of type container with the instance name: “container”
        • Inside “container” is another movie clip which is loaded via runtime sharing. “udk_main_menu.fla” for instance has the “main_menu” movie clip of type main_menu.
          • These movie clips have been imported into the SWF via runtime sharing from udk_assets.swf
          • UDK_assets.swf contains all the views in the library, and each view is setup to export for runtime sharing in the properties.
      • The newly loaded SWF fires off a CLIK WidgetInitialized event
    • Finally, we add the name of the view to the LoadedViews[] array.
  • WidgetInitialized() is executed for each loaded view as they are loaded.
    • Example: MainMenu
      • MainMenuView is created of type GFxUDKFrontEnd_MainMenu
      • Calls ConfigureView()
      • ConfigureView() is executed.
        • SetWidgetPathBinding() is called - this function sets it up so that all child widget's found in the view's path will send their initCallBack events to the view's WidgetInitialized() handler.
          • This requires using SubWidgetBindings.Add instead of the usual WidgetBindings.Add in the default properties when binding a widget.
      • Calls ConfigureTargetView() (only for MainMenuView)
  • ConfigureTargetView() is executed (for the first view ? main menu)
    • This function first tests to see if the view is already on the stack or not.
    • Calls OnViewActivated() (found in GFxUDKFrontEnd_View.uc)
    • Calls OnTopMostView(), passing true.
      • OnTopMostView() plays the open animation & sets the escape key delegate.
    • Adds the view to the UnrealScript ViewStack[] array.
    • Calls PushView().
  • PushView() is executed.
    • Fires off the ActionScript function pushStandardView() in MenuManager.as, passing it the new view.

MenuManager Call Stack


  • pushStandardView() is executed.
    • Calls pushViewImpl()
  • pushViewImpl() is executed.
    • Tweens the new view into place.
    • Pushes the new view onto the _viewStack[] array in AS.

"Popping" a View


When a view is "popped" off the viewstack, as when pressing BACK to go from the Multiplayer screen to the Main Menu, the essential functions used are:

  • PopView()
  • PopViewStub()

  • Each Screen has a "Back" button. The Back button is bound in GFxUDKFrontEnd_Screen.uc in the defaultproperites:

Unrealscript
defaultproperties
{
  // General
  SubWidgetBindings.Add((WidgetName="list",WidgetClass=class'GFxClikWidget'))
  SubWidgetBindings.Add((WidgetName="back",WidgetClass=class'GFxClikWidget'))

  AcceptButtonImage="pc_enter_png"
  CancelButtonImage="pc_esc_png"
  AcceptButtonHelpText="SELECT"
  CancelButtonHelpText="BACK"
}

  • In the WidgetInitialized() handler of GFxUDKFrontEnd_Screen.uc, the Back button is told to listen for 'CLIK_press' events, and to execute Select_Back() on press.:

Unrealscript
case ('back'):   
  BackBtn = GFxClikWidget(Widget.GetObject("btn", class'GFxClikWidget'));
  BackBtn.SetString("label", "BACK");
  BackBtn.AddEventListener('CLIK_press', Select_Back);
  BackBtn.AddEventListener('CLIK_focusIn', FocusIn_BackButton);
  bWasHandled = true;            
  break;

  • The event handler Select_Back() is found in GFxUDKFrontEnd_View. It fires off the function MoveBackImpl():

Unrealscript
function Select_Back(GFxClikWidget.EventData ev)
{
  MoveBackImpl();
}

  • MoveBackImpl() executes PopView() from the MenuManager (GFxUDKFrontEnd.uc)

Unrealscript
function MoveBackImpl()
{
  if (MenuManager != none)
  {
    PlayCloseAnimation();
    MenuManager.PopView();        
  }
}

  • PopView() removes the current view from the ViewStack[] array.

Unrealscript
ViewStack.Remove(ViewStack.Length-1, 1);

  • It then executes the OnTopMostView() function of the previous view (which is now the current view).

Unrealscript
ViewStack[ViewStack.Length-1].OnTopMostView( false );

  • Last of all, it executes the PopViewStub() function as its return value.
  • PopViewStub() executes the popView() ActionScript function found in MenuManager.as
  • popView() then executes popViewImpl() which tweens the movie out.

Downloads


  • Download the simplified version of GFxUDKFrontEnd.