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/UIElements. The 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.
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 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:
This can be defined in the xml as:
- 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.
It is also possible to define functions that are not in the rootspace of the Flash file, e.g.
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.
To handle this event add a <event> tag into the <events> list:
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.
To get or set a variable select the variable in the dropdown list of the UI:Variable:Var or UI:Variable:Array flownode.
Arrays are comma separated strings.
You can also access your defined MovieClips via FlowNodes.
Displaying an UI Element
To show or hide an 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).
There are three modes ("type") to place the asset on the screen:
In this mode the Flash asset is displayed on a fixed position, defined by a top, left, width and height value.
This mode aligns the asset on anchors. For vertical alignment it is possible to align the Flash element at the "top", "center" or "bottom",
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.
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.
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)
0=disabled, 1=enabled, if enabled a hardware mouse cursor is visible while the Flash element is displayed.
0=disable, 1=enabled, if enabled mouse events are send to the Flash file (mouse-clicks and movement.
0=disabled, 1=enabled, if enabled key events are send to the Flash element.
0=disabled, 1=enabled, if enabled the controller works as a mouse on console (thumb-stick). Only if mouseevents are enabled.
0=diabled, 1=enabled, if enabled a hardware cursor is displayed on console as well. Only if cursor is enabled.
0=disabled, 1=enabled, if enabled the flash file will receive automatically controller events from the game.
0=disabled, 1=enabled, if this is enabled this indicates that the flash file captures all the input events coming from the game exclusively.
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.
If set to true this element will not be unloaded on level unload (flag will be applied to all instances)!
0 to n, defines in which order the elements are displayed (if more than one Flash element is visible).
0 to 1, the background alpha of the Flash element.
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.