Essentials Series/User Interfaces

This page is part of the Essential Series modding tutorials. User Interfaces (UI or UIFT) are entity assets that create something which is rendered on the player's screen, on top of the game, such as a pause menu element. There are three basic UI types: model and texture (both are UI assets) and text (UIFT assets). These assets are able to send events based on gamepad input. UI and UIFTs are usually found in the Default layer of the level's HIP.

Using UI/UIFT
Industrial Park has generic UI and UIFT templates. Although they are entity assets, their use is different from most others.

Entity Fields

 * PositionX and PositionY: the position vector's X and Y values sets the position of the top left corner of the UI element, in screen coordinates (pixels). This means an object placed at X = 0 and Y = 0 will be at the very top left corner of the screen. The screen size is 640 x 480, so an object with Y = 480 will be at the very bottom of the screen. You can also place the assets outside of this range.
 * PositionZ: this sets the Z-ordering of the assets. Assets with higher values will appear behind assets with lower values. This has no influence on the size of the element.
 * Visibility Flags: if Visible is set, the element will start visible. If it's false, the element will start invisible.
 * Model AssetID: if this is set, the UI will use a model. If you want to use a texture or this is a UIFT, leave this at 0.

User Interface Fields

 * Texture AssetID: if this is set, the UI will use a texture. If this is a UIFT, leave this at 0.
 * Width and Height: these are important fields, specially in texture UIs and UIFTs. This will set the exact size of the element, in screen units (pixels). Remember to set those when placing a new UI/UIFT template.

UI Font Fields
These apply to UIFT (text), but not UI.


 * Text AssetID: this is the TEXT asset with the actual text that will be displayed by the asset.
 * FontID: there are 3 different fonts available (Spongebob, Arial and System), plus the Numbers font which only has numbers.
 * Font Color/Alpha: this will set the color and transparency of the text.
 * Background Color/Alpha: this will set the color and transparency of the background. The area of the background is exactly the values set in Width and Heigth (above). The background will only be visible if the correct flag is set.
 * UIFontFlags: most of these are unknown. Here you can set the text alignment (left, right or center) and also if the background is visible or not. A UIFT's background is a solid color.
 * Padding (top, bottom, left and right): this will set the border of the element, in pixels (how much free space between the border of the background and the text itself).
 * Spacing (horizontal and vertical): this will set the distance between the characters.
 * Char_Width and Char_Height: this will set the size of the characters.

Events
Events are a major part of working with UI/UIFT. There are two basic states for those assets: focused (on/off) and selected (on/off).


 * UIFocusOn: send this to a UI/UIFT asset to turn on focus.
 * UIFocusOff: send this to a UI/UIFT asset to turn off focus.

When you turn on focus for a UI/UIFT, the element will be visible. Turning off focus will make the element invisible. Focused elements are visible, but cannot use PadPress events.


 * UISelect: send this to a UI asset to select it.
 * UIUnselect: send this to a UI asset to unselect it.

Selecting a UI/UIFT will enable using PadPress events. Unselecting will disable the PadPress events. '''The asset must be focused for select to work. You cannot select an unfocused asset.'''


 * UIFocusOnSelect: send this to a UI asset to both focus and select it. The asset will be visible and will be able to use PadPress events.
 * UIFocusOffUnselect: send this to a UI asset to both unfocus and unselect it. The asset will be invisible and not able to use PadPress events.

The PadPress events are the main way to interact with UI/UIFTs. The asset will receive the event upon pressing the button if it is focused and selected. You can then use links to send events and possibly focus/select other UI/UIFT assets to create a custom menu, for example. The following events are available (they use PS2 button names, but they work for the equivalent buttons on GameCube and Xbox):


 * PadPressX
 * PadPressSquare
 * PadPressO
 * PadPressTriangle
 * PadPressL1
 * PadPressL2
 * PadPressR1
 * PadPressR2
 * PadPressStart
 * PadPressSelect
 * PadPressUp
 * PadPressDown
 * PadPressRight
 * PadPressLeft

UI Mode
In Industrial Park's Display tab, or by pressing U, you toggle between normal view mode and UI Mode: this is intended for editing of menus through UI and UIFT assets. The view will become a 2D 640x480 screen (this aspect ratio can be forced through the UI Mode AutoSize button). Those assets can also be edited in normal mode, but it's possible to have an approximate preview of them with UI Mode.



Custom UI/UIFT Examples
The following images show examples of custom UI elements. All three were placed from templates (two UIFT and one texture UI). The positions, width and height of the assets were set afterwards. Different TEXT, colors and flags were set for the UIFTs. As you can see, Industrial Park's UI Mode's preview is approximate, but not accurate to the game. The position of the elements is correct, but the text and colors do not appear.