Skip to end of metadata
Go to start of metadata

Overview

An UI element represents and defines a Flash asset (.swf file), that is usable by the engine. All UI Elements are defined as an XML script file located in GameSDK/Libs/UI/UIElementsThe XML file contains all the information, which the engine needs in order to use the Flash asset in game. 

 

Defining an UI Element

So imagine we have a HudElements Flash asset and we want to use it in the engine. You have to create a HudElements.xml file and save it in GameSDK/Libs/UI/UIElements as previously mentioned.

HudElements.xml
Icon

The sample also shows, that we can define multiple UI elements in one XML file, but it is a good practice to avoid this and create a separate XML file per UI element, to keep everything easy to find and manage complexity easier. It is up to the developer to decide how to organize this.

The XML script contains blocks for functions, events, variables, arrays, and movie clips. These blocks are used by the engine to create Flowgraph nodes automatically. The nodes can be used than in UI Actions or Flowgraph to script UI logic.

Functions

Functions that should be callable from outside ( UI Actions / Flowgraph ) need to be defined in the <functions> block of the element.

e.g. an actionscript function to set a health bar:

actionscrpit

This can be defined in the xml as:

hud.xml
  • The <function> block declares the function.
    • name="..." is the name of the function that is visible in the Flowgraph and funcname="..." is the real name of the function in the actionscript.
  • The <param> block declares, what parameters the function is supposed to receive.
    • name="..." is the name of the parameter as displayed in the Flowgraph node. (the function can contain multiple parameters)
    • desc="..." is the text, that will appear, if a user hovers over the parameter in Flowgraph. This is used to help other users, when they are using your Flowgraph nodes. If they don't know what a parameter is for, they can check the user friendly description provided by the developer.
    • type="..." is the type of the variable. It can be one of the following: int / bool / string / float . If you dont specify anything, the parameter will be of type "any" and node will try to convert the incoming value and pass it to Flash. It is a good practice to specify your parameter type to avoid potential problems.

The system will automatically create a node for the Flowgraph, with which we can call this function.

Icon

It is also possible to define functions that are not in the rootspace of the Flash file, e.g.

hud.xml

Events

To get notification about some user interaction, e.g. if a button was pressed, events can be defined in the <events> block. To trigger an event in your actionscript code you have to call fscommand("commandString"). These fscommands are handled by the engine.

e.g. in the onPress function of a button you can call fscommand with the string "onMyButtonPressed" and some arguments.

actionscrpit

To handle this event add a <event> tag into the <events> list:

hud.xml

The system creates a node to handle this event:

Variables, Arrays and MovieClips

Access to an array or a variable can also be defined in the xml file.

Just add a <variable> tag into the <variables> block, an <array> tag to the <arrays> block, or a <movieclip> tag into the <movieclips> block.

hud.xml

To get or set a variable select the variable in the dropdown list of the UI:Variable:Var or UI:Variable:Array flownode.

 

 

Icon

Arrays are comma separated strings.

You can also access your defined MovieClips via FlowNodes.

Displaying a UI Element

To show or hide a UI element use the UI:Display:Display node. You can select the element in the drop-down list. If the element is not in the list, this means there is something wrong with the XML script file defining the Flash asset.

To setup the behavior and the constraints use the UI:Display:Config and UI:Display:Constraints nodes.

It is also possible to initialize all of those settings in the XML file. Keep in mind that, by doing this all of your UI Elements of this type will share the same configuration / constrains (it is still possible to customize it on per instance basis).

hud.xml

Constraints

There are three modes ("type") to place the asset on the screen:

Type

Description

fixed

In this mode the Flash asset is displayed on a fixed position, defined by a top, left, width and height value.

dynamic

This mode aligns the asset on anchors. For vertical alignment it is possible to align the Flash element at the "top", "center" or "bottom",
for horizontal alignment to the "left", "center" or "right" of the screen.

fullscreen

In this mode the viewport of the asset is same as the render viewport. If scale is set to "1" the asset is stretched to fit the complete screen, otherwise not.

scale

If set to "1", it tries to scale the element to the maximum without deforming the aspect ratio. If set to "0", it will not scale the Flash asset.

maximize

If set to "1", it will maximize the element so that 100% of the screen is covered (this might cause that some parts of the element are cut-off)
otherwise the asset will fit to the screen with maybe some uncovered space on the left/right or top/bottom side

Configuration

Configuration

Description

cursor

0=disabled, 1=enabled, if enabled a hardware mouse cursor is visible while the Flash element is displayed.

mouseEvents

0=disable, 1=enabled, if enabled mouse events are send to the Flash file (mouse-clicks and movement.

keyEvents

0=disabled, 1=enabled, if enabled key events are send to the Flash element.

consoleMouse

0=disabled, 1=enabled, if enabled the controller works as a mouse on console (thumb-stick). Only if mouseevents are enabled.

consoleCursor

0=diabled, 1=enabled, if enabled a hardware cursor is displayed on console as well. Only if cursor is enabled.

controllerInput

0=disabled, 1=enabled, if enabled the flash file will receive automatically controller events from the game.

eventsExclusive

0=disabled, 1=enabled, if this is enabled this indicates that the flash file captures all the input events coming from the game exclusively.
This can be used in combination with the layer property (e.g. modal dialogs). Internally the system works in the following way.
When an input event is triggered, the UI system starts from UI element with highest layer value that is visible. If this element accepts the input event type it processes it.
After that the system checks if this element has the eventsExclusive flag on and if it does, it doesn't propagate the event further down to the other UI elements underneath.
To sum this up, only the top layer is capturing all the input events.

fixedProjDepth

If set to true this element will use pseudo 3D mode. The _z value of each movie-clip will only affect its size to give the feeling of "correct" depth.

forceNoUnload

If set to true this element will not be unloaded on level unload (flag will be applied to all instances)!

layer

0 to n, defines in which order the elements are displayed (if more than one Flash element is visible).

alpha

0 to 1, the background alpha of the Flash element.

Instancing

What is the purpose of the "InstanceID" port in all the UI nodes? With this instance ID you can have more than one instance of a particular type of Flash asset and dispatch commands only to that node. The "InstanceID" port of any UI node defines which instance should be affected by this node. If you use a node with a new instance ID it will automatically create the new instance of this Flash asset.

If you use "-1" as the instance ID, the node will affect all instances of this UI element, which are currently available (if there are none, it will create one).

If you use "-2" as the instance ID, it will trigger the node functionality on all initialized instances of this UI element.

 

Functions Reserved and Used by the Engine

There are some special actionscript functions that are automatically called by the UI system, when certain conditions are fulfilled.

These functions have to be defined in the rootspace of your actionscript and don't need to be specified in the UI Element XML file.

cry_onSetup - If this function exists, it is called once the UI element is initialized by the engine.
cry_onShow - If this function exists, it is called when the UI element is made visible. (via Flowgraph / code / LUA)
cry_onHide - If this function exists, it is called the UI element is hidden. (via Flowgraph / code / LUA)
cry_onResize - If this function exists, it is called when the resolution of the engine has changed.
cry_requestHide - If this function exists, it is called if the "RequestHide" port was triggered on a UI:Display:Display Node (or via code / Lua).
cry_onController - If this function exists, it is called if an input event from a controller has been triggered by the engine.
cry_onVirtualKeyboard - If this function exist, it is called when an input event from a virtual keyboard has been triggered by the engine.
cry_hideElement - If a fscommand is executed with this string, it tells the UI System to hide the UI element.
  • No labels